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LIST OF NEW FEATURES IN INFORMIX 3.20 


The following list of features describes the new 
features in INFORMIX 3.20. 
The program lines in' 
this section only give an idea of the syntax of the 
new features, they are not actual programs and will 
not run on your machine. 
Refer to the appropriate 
chapter of the INFORMIX manual for specific 
information on how to use each of the new features. 


CONTROL ACCESS - 
INFORMIX System 


This is an addition to the current access 
permissions allowed by INFORMIX. 
Control Access is 
the permission to add and delete indexes or 
permanent files, 
rename fields or files, rebuild an 
existing file, 
or any other operation that can 
change either the database dictionary or the data 
files themselves. 
Control Access is added just like 
any other access permission -- inside the schema 
that is compiled with DBBUILD. 


CHECK AND REPAIR FILE - 
DBSTATUS 


This command uses the code already in BCHECK to 
check on the correctness of INFORMIX database files 
and to repair them when something is wrong. 
The 
syntax is shown below. 


check file file name 
repair file file_name 


LOCK EXCLUSIVE - 
INFORMER 


This command allows a user to lock a file 
exclusively using INFORMER. 
Its syntax is shown 
below. 


lock exclusive file name 


UNLOAD ASCII - 
INFORMER 


This command allows users to unload, in ASCII 
format, permanent and temporary database files from 
INFORMER. 
The syntax for this command is identical 
to the syntax used in DBSTATUS. 


INFORMIX 
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SELECT DATABASE - 
INFORMER 


This command Allows users to change from one 
database to another without the current requirement 
of leaving and then re-entering the 
INFORMER query 
language. 


DATE FUNCTIONS - 
INFORMER/ACE 


Currently there is no way to extract just the day, 
month, or year part of a field having data type 
DATE. 
This makes groupings on month and year rather 
difficult inside ACE. 
The functions 
DAY, 
MONTH, 
YEAR have been added to INFORMER and ACE. 
In ACE 
these functions have been implemented both in the 
query and format sections. 
Their syntax is as 
follows: 


newname 
= day(expression) 
newname 
= month(exoression) 
newneme 
= year(expression) 


In use, they might look like this. 


read listings 
where month(date listed) 
= 2 
end yeer(date:listed) > 82; 


before group of months 


after group of years 


Or like this. 


read into first of month tasks reminders 
where day(;emInder_date) 
= 1; 


MDY function 


Other date manipulation functions include MDye) 
whose function is to convert any combination of 
three expressions into a data type date field. 
Its 
use is shown below. 


read listings, new date 
= mdy(12,1,84); 
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WEEKDAY function 


The 
WEEKDAY function allows the user to see on what 
day of the week a particular date lies. 
The 
function returns an integer which is 0 (zero) for 
Sunday, 
1 for Monday, etc. 
Its syntax is shown 
below. 


if (weekday(today) = 5) then 
print "Today is Friday." 


DATE, 
EDATE, and YDATE functions 


The remaining date functions in INFORMER and ACE 
allow a user to change any expression into a 
temporary field of type DATE, 
EDATE, or YDATE. 


Their syntax is as follows: 


new field 
new-field 
new-field 


date(expression) 
= edate(expression) 
ydate(expression) 


COLUMN print item - 
ACE 


The 
COLUMN print item allows users to print items in 
ACE at specifiable column positions. 
A sample is 
shown below. 


print column 43, "First Name", 
column 56, 
"Last Name" 


print column 43, first name, 
column 56, 
last_name 
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NEED LINES - 
ACE 


The NEED LINES statement of ACE allows users to be 
sure that enough room remains on the current page of 
output before printing a section of output. 
This 
feature is similar to the "keep" construct of 
"nroff." It works like this. 


before group of last-name 


need 5 lines 
print last name 
print address 
print address2 
print phone 
print zip 


The above clause will be assured of printing all on 
the same page. 
Before printing "last name" ACE will 
check that there are at least five text lines 
available on the current page. 


ASCII print item - ACE 


The ASCII print feature of ACE allows users to 
output non-printable characters. 
This is useful 
when users want a special characteristic of a 
printer or terminal to be used for an interesting 
effect during a printing of an ACE report (i.e., 
bold type, colored output). 


let red output = ascii 9, ascii 11, ascii 1 
let color_off 
= ascii 9, ascii 11, ascii 0 


print red output, 


"Your bill was due weeks ago!!!", 
color off 


... . 
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Introduction 


I. 
What Is a Database Management System? 


A database is an organized collection of infor- 
mation. 
A database management system (DBMS) allows 
you to enter, store, manipulate, and retrieve infor- 
mation organized into databases. 
A DBMS provides 
interactive access to your databases and provides 
easy ways to create printed reports. 


When a body of information becomes too large or 
the retrieval demands on it become too complex to 
manage manually, the information system should be 
computerized. 


Every computer application has unique require- 
ments. 
For example, special-purpose software sys- 
tems that handle personnel, inventory, and marketing 
data may differ not only in the type of information 
they store, but also in the facilities they provide 
for data entry and retrieval. 


The cost of designing and building special- 
purpose software systems for data management tasks 
often prohibits otherwise cost-effective automation. 
Database management systems are general-purpose pro- 
grams that dramatically reduce the time necessary to 
computerize an application. 
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II. 
What Is a Relational Database System? 


The sample database distributed with INFORMIX 
shows how a retail store might set up an information 
system about its customers and the items those cus- 
tomers have ordered. 


This information is organized in two groups, 
commonly called "files." 
The customers file con- 
tains each customer's name, address, and balance. 
The orders file contains the customer's name, the 
item ordered, and the quantity ordered for each 
item. 
A database often contains many files. 


The way you organize information for a particu- 
lar application is usually dictated by your informa- 
tion retrieval requirements. 
Information should be 
stored in a format that allows the database software 
to answer questions quickly and produce reports ef- 
ficiently. 


Typical questions that might be asked by the 
users of this database are "Which customers have 
paid their bills?" and "What are the items that are 
on order by those people?" 
INFORMIX provides an in- 
teractive query language to answer such questions. 


The answer to the second question requires in- 
formation from both files in the database shown in 
Figure 1. 
The ITEM field is in the orders file, but 
the customers file contains the information about 
who have paid their bills (those who have a zero 
balance in the BALANCE field). 


The question can be answered because the two 
files both contain the customer's name. 
Once the 
customers who have paid their bills have been 
selected from the customers file, 
those names can be 
used to look up the items they have on order in the 
orders file. 


INFORMIX is designed to process these cross- 
file queries. 


In non-relational systems, a cross-file query 
can be answered only if the link between the files 
has been described to the system. 
Such relation- 
ships must be defined when the database is designed 
and created. 


As databases grow, they can acqUire new files 
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with new relationships. 
Typically, there are dozens 
of useful relationships among database files. 
With 
a relational database system, the query language can 
use any relationship that exists between files at 
any time. 
You don't have to predict the requirement 
for a relationship when you design the database. 


In the vocabulary of the relational model, a 
file with a table-like structure like the one in 
Figure 1 is referred to as a "relation." The rows of 
the tables, or "records," are called "tuples" in re- 
lational jargon. 
"Field" names, such as CNAME and 
ADDRESS, are called "attributes." 


For the sake of clarity, the !NFORMIX documen- 
tation uses the more widely accepted terms "file," 
"field," .and "record." 
When itis important to dis- 
tinguish between a file in an INFORMIX database and 
an operating system file, the phrase "database file" 
is used. 


INFORMIX is a true "relational" database 
management system, according to the definition of 
"relational" developed by E. F. Codd of the IBM Cor- 
poration during the 1970s. 
INFORMIX is based upon 
the "relational algebra" and can be proven to be re- 
lationally complete. 
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customers file 


cname 


Brooks, B. 
Field, W. 
Robin, R. 
Hart, 
W. 


Court, S. 
English, 
D. 


orders file 


oname 


Brooks, B. 
Brooks, B. 
Robin, R. 
Hart, 
W. 


Robin, R. 
Court, S. 
Court, S. 
English, 
D. 
English, 
D. 


address 


7 Apple Rd. 
43 Cherry Ln. 
12 Heather Ct. 
65 Lark Rd. 
56 Blossom Rd. 
82 Alpine Rd. 


item 


Work Bench 
Saw 
Work Bench 
File 
Hammer 
Saw 
File 
File 
Hammer 


Introduction 


balance 


10.50 
0.00 
23.45 
43.00 
0.00 
0.00 


quantity 


5 
1 
3 
3 
8 
3 
5 
1 
2 


Figure 1. The stores database 
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III. 
Overview of INFORMIX 


The INFORMIX database management system is a 
collection of computer programs that provide com- 
plete facilities for data definition, data entry, 
data retrieval, and reporting. 


The most commonly used INFORMIX programs are: 


• 
The Master Menu, from which you can call other 
INFORMIX programs and commands 


• 
DBBUILD, a data description language that al- 
lows you to create and modify database files 


• 
FORMBUILD, with which you create custom- 
designed screen forms for data entry 


• 
PERFORM, a data entry and query facility for 
use with custom-designed forms 


• 
INFORMER, a query language for data retrieval 


• 
ACE (composed of ACEPREP and ACEGO), for creat- 
ing and printing custom-formatted reports 


• 
DBSTATUS, the database monitor 


The other programs that make up the INFORMIX 
system are 


• 
ENTER2, a data entry program that is simpler 
than PERFORM 


• 
ENTER1, a data entry program for use with hard 
copy terminals (not provided with MS-DOS ver- 
sions of INFORMIX) 


ALL-II, an application language library that 
serves as an interface between conventional 
programming languages and INFORMIX routines 


DBMENU, which allows you to design your own 
menus for customized applications 


BCHECK, a facility for checking indexes 
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You can terminate any command given to an in- 
teractive INFORMIX program by pressing the DELETE or 
RUBOUT key. 
On some computer terminals this key is 
labeled RUB or DEL. 


III.A. 
The Master Menu 


To call the INFORMIX Master Menu from the 
operating system, type 


~ informix 


Under UNIX, the following screen is displayed. 


INFORMIX Master Menu 
INFORMIX version 3.2 
Copyright (C) 1981, 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-000001 


1. 
2. 
3. 
4. 
5. 
6. 
7. 
8. 
9. 


Perform 
Acego 
Informer 
Select 
Dbatatus 
Schema 
Enter2 
Enter1 
Syatem 


Data entry and query by forms 
Run Ace report 
Query language 
Database selection 
Database administration 
Print database schema 
Screen-oriented data entry 
Data entry 
Operating system command 


Use apace bar, arrow keys, or type number to make selection. 
Enter 'b' to exit. 
Enter carriage return to execute selection: 


Under MS-DOS, the Master Menu does not include 
Options 8 and 9. 
Otherwise, it is identical. 


You can give a database name on the operating 
system command line: 


~ informix realty 


In this case, 
INFORMIX selects the database you 
specify when the Master Menu is first displayed. 
The message "Database realty selected" appears on 
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the bottom line of the screen. 


Under MS-DOS, be sure to specify the drive or 


volume on which the database resides (or set the ap- 
propriate environment variables so that INFORMIX can 
find the database you specify). 


In response to the command shown above, the 
screen looks like this: 


INFORMIX Master Menu 
INFORMIX version 3.2 
Copyright (Cl 1981, 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-000001 


1- 
2. 
3. 
4. 
5. 
6. 
7. 
8. 
9. 


Perform 
Acego 
Informer 
Select 
Dbstatus" 
Schema 
Enter2 
Enter1 
System 


Data entry and query by forms 
Run Ace report 
Query language 
Database selection 
Database administration 
Print database schema 
Screen-oriented data entry 
Data entry 
Operating system command 


Use space bar, arrow keys, or type number to mske selection. 
Enter 'b' to exit. 
Enter carr"iage return to execute selection: 


Database "realty" selected. 


If you do not specify a database name on the 
command line, you can do so with Option 4 on the 
Master Menu. 
INFORMIX lists the databases in the 


current directory (or, if the DBPATH environment 
variable is set, the databases in the directories 
named in DBPATH). 
If only one database is avail- 
able, 
INFORMIX selects it automatically. 
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INFORMIX 
Maste~ Menu 
INFORMIX 
ve~sion 3.2 


Copy~ight (Cl 1981, 1982, 1983 Relational Database Systems, Inc. 


Softwa~e 
Se~ial 
Numbe~ RDS-000001 


1. 
2. 
3. 
4. 
5.6. 
7. 
9. 
9. 


Pe~fo~m 
Acego 


Info~me~ 
Select 
Dbstatus 
Schema 


Ente~2 


Ente~1 
System 


Data 
ent~y and 
que~y by 
fo~ms 


Run Ace 
~epo~t 


Que~y language 
Database selection 
Database 
administ~ation 


P~int database schema 


Sc~een-o~iented data 
ent~y 


Data 
ent~y 


Operating system command 


Use space 
ba~, 
a~~ow keys, 
o~ type 
numbe~ to make selection. 


Ente~ 'b' to exit. 


Ente~ 
ca~~iage 
~eturn to execute selection: 
4 


The following databases 
a~e available: 


1. bank 


2. menu 


3. 
~ealty. 


4. 
sto~es 


Use space 
ba~, 
a~~ow keys, 
o~ type 
numbe~ to make selection. 


Ente~ 'b' 
to exit. 


Ente~ 
ca~~iage 
~etu~n to execute selection: 


If you do not specify the current database on 
the operating system command line or with Option 4 
on the Master Menu, then the first INFORMIX program 
you run asks for the name of a database. 
If only 
one database is available, 
INFORMIX selects it au- 
tomatically. 
You can always change the current da- 
tabase with Option 4 on the Master Menu. 


INFORMIX 
11 


Introduction 


III.B. 
DBBUILD Data 
Desc~iption Language 


With the DBBUILD data description language, you 
can create and modify database files. 


The first step in creating INFORMIX database 
files is to analyze your application and design a 
database structure. 
For each database file you want 
to create, you put information about its fields in a 
"schema" in an operating system text file. 
DBBUILD 
compiles the- schema file, creating the database 
file. 


INFORMIX database files are implemented as two 
operating system files, one for data and one for 
indexes. 
The name of the operating system file that 
holds data ends with the characters .dat and the 
name of the file that holds the indexes ends with 
.1dx. 


For each database, another operating system 
file, which holds the database dictionary, is also 
created when the 
fi~st file in the database is com- 
piled. 
The name of the file holding the database 
dictionary ends with .dbd. 
The database dictionary 
contains information about the database structure 
and is used by all the INFORMIX programs that access 
the database. 


INFORMIX puts no limit on the number of files 
in a database. 
For most computers that run INFOR- 
MIX, the number of files is limited only by the 
operating system and the amount of available main 
memory. 


The UNIX operating system provides password 
protection for the files in an INFORMIX database. 
With INFORMIX under UNIX, you can specify additional 
permissions for a database file or for individual 
fields in the schema. 
INFORMIX under MS-DOS does 
not support permissions. 
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III.C. 
FORMBUILD and PERFORM 


With PERFORM and FORMBUILD, you can design cus- 
tomized screen forms for data entry and simple 
queries. 


PERFORM allows you to browse through records or 
find records based on search values. 
Once a record 
is displayed, you can delete or modify it. 
You can 
also add new records. 
PERFORM provides sophisticat- 
ed data checking. 


To design a customized screen form, 
you build a 
form specification file with a text editor and then 
compile it with FORMBUILD. 
You can place fields on 
the screen wherever you like with whatever labels or 
titles you like. 
You can include more fields than 
can fit on one screen, and you can create forms with 
fields from more than one file. 


111.0. 
INFORMER 


The INFORMER query language" is an interactive, 
English-like language for data manipulation and re- 
trieval. 
INFORMER can display or print to a tem- 
porary database file any file or subseot of a file. 
Since it is based on the relational database model, 
INFORMER can also provide answers to cross-file 
questions. 


Under UNIX, you can enter a query into an 
operating system file and execute it interactively 
by using 
IN~ORMER's EXECUTE command. 
You can also 
create executable files that prompt for user input 
when they are run. 
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III.E. 
The ACE Report Writer 


The ACE relational report writer provides the 
same query power as INFORMER but with powerful and 
flexible formatting facilities. 
Standard data pro- 
cessing arithmetic operations can be performed with 
ACE, 
including aggregate operations such as TOTAL, 
PERCENT, COUNT, and AVERAGE. 


III.F. 
DBSTATUS 


DBSTATUS is a command-driven interactive 
language for optimizing the performance and modify- 
ing the structure of INFORMIX databases. 
You can 
use DBSTATUS to: 


• 
Add or delete indexes 


• 
Print a file's schema or status 


• 
Erase files or entire databases 


• 
Start or stop audit trails 


• 
Load or unload database files to or from 
operating system files 


You can specify indexes and audit trails in a 
DBBUILD schema, and delete them or add new ones at 
any time with DBSTATUS. 
There is no limit to the 
number of fields that can be indexed. 


III.G. 
System-vide Commands 


The PRINT SCHEMA and PRINT STATUS commands are 
available from several INFORMIX programs. 


PRINT SCHEMA is available from DBSTATUS in its 
complete form, and in its simple form from ENTER1, 
INFORMER, and the Master Menu. 


The PRINT STATUS command, which shows informa- 
tion about the size of the database files and the 
indexes that exist, is available from DBSTATUS in 
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its complete form, and in its simple form from IN- 
FORMER 
~nd ENTER1. 


III.H. 
Number of Open Files 


The number of database files that INFORMIX can 
open simultaneously determines the number of files 
you can use in a cross-file query and the number you 
can use on a PERFORM form. 
This limit varies 
depending on the operating system you use and wheth- 
er or not you are using audit trails. 


UNIX allows 20 open files. 
Of these, 4 are re- 
quired by the operating system, leaving 16 for IN- 
FORMIX. 
In versions of UNIX that handle concurrency 
control automatically, 8 INFORMIX files (each con- 
sisting of a .dat file and an .idx file) 
can be open 
simultaneously if you do not use audit trail files. 


If all your database files have audit trails 
associated with them, you can open 5 INFORMIX files 
(each consisting of a .dat file, an .idx file, and 
an audit trail file). 


In versions of UNIX that do not handle con- 
currency control automatically, 
INFORMIX creates a 
.lok file for each database file. 
This means that 5 
INFORMIX files can be open simultaneously if you do 
not use audit trails, and 4 INFORMIX files if you 
use audit trails. 


MS-DOS also allows 20 open files •. Five are re- 
qUired by the operating system, leaving 15 for IN- 
FORMIX. 
Thus, you can open 7 files if you do not 
use audit trails and 5 if you use audit trails on 
every database file. 


Additionally, in PERFORM, 
lookup fields count 
toward the file limit. 
Each lookup field (or group 
of lookup fields from a single file) counts as one 
file toward the limits specified here. 
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IV. 
Technical Specifications 


CPU REQUIREMENTS 


Max RAM required for any INFORMIX program 
128K 


Typical RAM requirements on UNIX machines 
(includes operating system) 


Single user 
Small multi-user (2-10 users) 
Large mul ti-user 


Minimum RAM requirements (MS-DOS) 


Disk space requirements 


Programs 
Libraries 
Include files 


256K 
512K 
1MB 


256K 


593K 
259K* 
7K 


*Library files are 
~ot included in the standard 
MS-DOS version. 


GENERAL DATABASE SPECIFICATIONS 
(Maximum specifications except as noted) 


Number of files per database 
Number of fields per database 
Number of records per file 
Record size 
Number of fields per record 
Field size 
Number of secondary indexes 
Size of composite keys 


16 


UNLIMITED 
UNLIMITED 
UNLIMITED 
2048 bytes 
2048 
2048 
UNLIMITED 
120 bytes, 
1-8 fields 
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DATA TYPES 


CHARACTER 
COMPOSITE 
DATE 
mm/dd/yy 
European date (dd/mm/yy) 
year date 
(yy/mm/dd) 


DOUBLE 
FLOAT 
INTEGER 
LONG 
MONEY 
SERIAL 


INFORMER AND ACE SPECIFICATIONS 
(Maximum specifications except as noted) 


Output line length 
Number of open files 
Files in a report 
Joined files in a read statement 
Joins in a report 
Fields in a report 
User variables 
Aggregate variables 
Levels for sorting 
Combined length of sort fields 


256 characters 
8 UNIX, 7 MS-DOS* 
UNLIMIrED 
8 UNIX, 7 MS-DOS* 
UNLIMITED 
200 
100 
100 
8 
120 


*Varies based on operating system constraints 
and the existence of audit trails 


PERFORM SPECIFICATIONS 
(Maximum specifications except as noted) 


Number of files per form 
Number of screens per form 
Number of fields per form 


8 UNIX, 7 MS-DOS* 
MACHINE DEPENDENT 
MACHINE DEPENDENT 


*Varies based ort operating system constraints 
and the existence of audit trails and lookup fields 
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C-ISAM SPECIFICATIONS 
(Maximum specifications except as noted) 


Number of indexes 
Record length 
Number of ISAM files open 
Key size 
Minimum RAM requirements 
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UNLIMITED 
2048 bytes 
8 
120 bytes, 1-8 fields 
16K code, 
8K data 
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V. 
INFORMIX under UNIX 


V.A. 
Operating System Commands 


Under UNIX, you can run an operating system 
command from within INFORMIX. 
Either select Option 
9, System, from the Master Menu, or enter the com- 
mand with an exclamation point from ENTER1, ENTER2, 
DBSTATUS, 
INFORMER, or PERFORM. 
For example: 


> !Is -1 


The exclamation point indicates that the 
remainder of the line is to be passed to the operat- 
ing system for execution. 
INFORMER's RUN command 
has the same effect. 


V.B. 
Read and Write Permissions 


Under UNIX, every file or directory is assigned 
a set of permissions that determines user access. 
These permissions can be displayed using the "Is _1" 
command. 
The nine characters following the first 
show the permissions. 
A typical listing follows. 


% Is -1 


-rw-rw----' 1 susan 
871 Apr 21 16:04 bank.dbd 
-rw-rw-rw- 1 susan 
465 Apr 14 11:18 emp. sch 
-rw-rw---- 1 susan 
2464 Apr 15 11:54 employee.dat 
-rw-rw---- 1 susan 
2560 May 11 11:00 employee.idx 
-rwxrwxrwx 1 john 
962 May 16 14:45 form2 


-rw------':'" 1 john 
1278 May 16 14:45 form2.frm 
drwxrwxrwx 2 john 
48 Apr 10 10: 10 scripts 


The first character of the permissions list is 
always a "d" (directory) or "-" (plain file). 
The 
remaining nine characters can be viewed as three 
sets of three characters each. 


The first set of three defines the access 
privileges of the owner of the file (susan or john 
in the example above). 
The second set applies to 
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the operating system user-group, of which the file's 
owner is a member. 
The final set applies to all 
other users of the system (public). 


The characters r, w, and x mean that read, 
write, and execute permissions are "turned on." A 
hyphen in place of one of these characters indicates 
that that type of access is not permitted. 


In the example above, the file emp.sch, which 
is owned by susan, may be read or written by the 
owner, the owner's group, or any other user of the 
system. 
The file bank.dbd may be read or written 
only by susan and those in her group of users. 
The 
file form2 may be read, written, or executed by any 
user of the system, but form2.frm can be read and 
written only by john. 
scripts is a directory which 
may be read, written, or searched by any user of the 
system. 


Permissions can be changed by the owner of the 
file or directory (or by the super-user) using the 
"chmod" (change mode) command. 
The mode is usually 
specified by a three-digit integer ranging from 000 
to 777. 


The first digit of the mode defines access 
priVileges for the file or directory owner. 
The 
second digit defines access for the owner's user 
group. 
The last digit applies to all other users of 
the system. 
A 1 allows execute permission, a 2 al- 
lows write permission, and a 4, read permission. 
The numbers may be added to allow multiple 
permis~ 


sions. 
A 7 represents all three permissions (1 
+ 2 
+ 4), a 6 would be write and read permissions only, 
etc. 
Thus, the command 


~ chmod 664 bank.dbd 


will change the mode of the bank.dbd file to allow 
read and write permissions for the owner and the 
owner's user group, and read permission for all oth- 
er users of the system. 
An "Is _1" of this file 
after the above command would look like this. 


-rw-rw-r-- 1 susan 
871 Apr 21 16:04 bank.dbd 


The table below reflects the permissions re- 
qUired to allow a user to use specific INFORMIX 
functions. 
(The columns with "__" indicate that 
permission restrictions on that file are irrelevant 
to the operation in question.) 
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INFORMIX also allows additional security 
restrictions which operate in addition to the 
operating system permissions. 
See "User Access 
Privileges" in the DBBUILD section for more informa- 
tion. 


-------database files------- database 
.dbd 
.idx 
.dat 
.frm 
.ar c directory 


DBBUILD 
rwx 


DBSTATUS 
rw 
rw 
rw 
rwx 


ENTER1 
rw 
rw 
rw 
rwx 


ENTER2 
rw 
rw 
rw 
rwx 


PERFORM 
rw 
rw 
rw 
I' 
rwx 


INFORMER 
queries 
rw 
rw 
I' 
rx 


wri ting to 
current 
directory 
rw 
rw 
I' 
rwx 


updates 
rw 
rw 
rw 
rwx 


ACE 
run report 
rw 
rw 
I' 
I' 
rx 


output report 
to current 
directory 
rw 
rw 
I' 
I' 
rwx 


V.C. 
Terminal Types 


Under UNIX, in order to properly run INFORMIX's 
screen-oriented programs (ENTER2, 
PERFORM, and the 
Master Menu), it is necessary to correctly define 
the type of terminal you are using. 


Terminal definitions are usually found in the 
file /etc/termcap. 
If no termcap file is present on 
your system, or the terminal being used is not de- 
fined in the termcap file, the termcap file shipped 
with INFORMIX can be used. 
If the correct defini- 
tion is still not found, consult your hardware 
dealer to obtain 
th~ proper termcap entry. 
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Incorrect or non-existent terminal definitions 
may confuse the display or cause the cursor to be in 
the wrong place in ENTER2, PERFORM, or the Master 
Menu. 
If the "vi" text editor works correctly, the 
terminal definition for your type of terminal is 
probably correct and INFORMIX should work with your 
terminal. 
If "vi" does not work correctly, then 
neither will INFORMIX. 


To specify the terminal type, use the "set" or 
"setenv" command, depending on the version of the 
shell in use. 
In the C shell, the command would be 


% setenv TERM d1 


where d1 represents the terminal type. 
If the C 
shell is not used, the commands are probably 


% TERM=d1 
%export TERM 


For more information, consult the Installation 
letter shipped with INFORMIX. 


Four INFORMIX programs (the Master Menu, 
DBMENU, ENTER2, and PERFORM) take advantage of spe- 
cial codes that video terminals understand (such as 
clear the screen, paint the screen, etc.). 
They 
cannot be used on a hard copy terminal. 


V.D. 
Environment Variables 


INFORMIX allows the use of two UNIX environment 
variables, 
DBPATH and DBTEMP. 


DBPATH specifies the search path INFORMIX uses 
to access database dictionary (.dbd) files. 
You can 
use the LOCATION option in DBBUILD to put a database 
dictionary file in a directory other than the direc- 
tory in which the data file (.dat) and index file 
(.idx) reside. 


With DBTEMP you can control the location of 
temporary files created by INFORMER and ACEGO. 


These procedures are fully documented in the 
DBBUILD and INFORMER chapters of this manual. 
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V.E. 
Text Editors 


Use of a UNIX text editor is necessary to 
create schema files for DBBUILD, form specification 
files for FORMBUILD, and report specification files 
for ACEPREP. 
Commonly available UNIX text editors 
are "vi," "ex," and "ed." 
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VI. 
INFORMIX under MS-DOS 


INFORMIX version 3.2 runs under MS-DOS 2.00. 
With earlier versions of MS-DOS, you must use INFOR- 
MIX versions 3.06A or 3.06B. 


RDS recommends that INFORMIX be used with MS- 
DOS on a hard disk. 
The minimum amount of RAM re- 
quired is 256K. 


Any references in the INFORMIX user's manual ,to 


the commonly used UNIX prompt 
~ or to UNIX commands 
such as "cat" and "nroff" should be disregarded if 
you are using INFORMIX under MS-DOS. 


The MS-DOS prompt is the drive specification, 
often A: followed by the symbol >. 
You can use the 
MS-DOS command TYPE to view a file and EDLIN to edit 
a file. 


VI.A. 
Modifying config.sys 


Before you begin, you must edit the MS-DOS file 
CONFIG.SYS on the drive you use to boot the system. 
Set the FILES variable to 40. 
Set the BUFFERS vari- 
able to a minimum of 8. 
The larger this number is, 
the better INFORMIX will perform. 
You must reboot 
the system after editing CONFIG.SYS. 
If you need 
help with this procedure, consult the MS-DOS manual. 
If you do not set the FILES variable, 
INFORMIX 
may not be able to access your database files. 
Changing the BUFFERS variable will improve 
INFORMIX's performance. 
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VI.B. 
Concurrency Control 


Since INFORMIX runs as a single-user system 
under MS-DOS, no concurrency control is provided in 
the data entry modules. 
Furthermore, the LOCK and 
UNLOCK 'commands in INFORMER, the DBLOCK and DBUNLOCK 
calls in ALL-II, and the UNLOCK FILE command in 
DBSTATUS, have no effect. 


VI.C. 
Case-sensitive Commands 


You can give INFORMIX commands under MS-DOS in 
any combination of upper- or lowercase letters. 
However, the "flags" or "switches" used with some 
INFORMIX commands must be lowercase. 
(The flags are 
the "-r" in "dbbuild -r", the "-v" in "formbuild 
-v", the "-d" in "formbuild -d", the "-q" in "in- 
former -q", and the "-q" in "acego -q".) 


VI.D. 
Environaent,Variables 


MS-DOS 2.00 supports a directory structure 
similar to that used by UNIX. 
The MS-DOS command 
SET can be used to set the environment variables 
DBPATH, 
DBTEMP, and PATH. 


DBPATH specifies the search path INFORMIX uses 
to' access database dictionary (.dbd) files. 


With DPTEMP you can control the location of 
temporary files created by INFORMER and ACEGO. 


PATH specifies a search path for INFORMIX and 
other programs. 


These procedures are fUlly documented in the 
DBBUILD and INFORMER'chapters of this manual. 
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VI.E. 
Text Editors 


Use of a text editor is necessary to create 
schema files for DBBUILD, form specification files 
for FORMBUILD, and report specification files for 
ACEPREP. 


The MS-DOS editor is called EDLIN. 
You can 
also use another word-processing program, as long as 
it does not generate invisible control characters. 


VI.F. 
Pipes 


MS-DOS 2.00 does not support pipes, so INFORMIX 
features that use pipes are not supported. 


VI.G. 
ACE Library and ALL Linking 


The C programmers' package consists of the Ap- 
plication Language Library (comprised of the files 
libdb.lib and dbio.h) and an ACE library (comprised 
of the files libace.lib and ace.h). 
The files 
rdsmain.c and rdsmain.obj are also a part of the C 
programmers' package. 


To use these C language programming tools, you 
must have the Lattice C compiler version 2.0. 
Com- 
pile your C programs with Lattice 2.0 using the P- 
model option, and link them with the Lattice C P- 
model library and the RDS ALL library. 


For example, to compile and link an ALL program 
called myprog, give the commands 


>lc1 myprog -mp 
>lc2 myprog 
. 
>link cp+myprog,myprog"libdb+lcp 


To compile and link a C program called yourprog 
with ACE, give the commands 
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>lc1 yourprog -mp 
>lc2 yourprog 
>link cp+yourprog+rdsmain,yourprog"libace+lcp 


VII. 
Integration With C-ISAM Files Built by COBOL, 
C, BASIC, or 
Oth~r Programming Languages 


A number of features of INFORMIX version 3.2 
ease the integration of INFORMIX with C-ISAM files 
built by COBOL or other programming languages. 


ByCdesignating a PRIMARY KEY, the user can 
eliminate the need for an INFORMIX-assigned unique 
identifier. 
While this identifier creates no prob- 
lems for most applications, it ·can create compati- 
bility problems with C-ISAM files built with COBOL, 
or other programming languages. 
The optional desig- 
nation of a PRIMARY KEY allows the programmer to 
avoid these potential problems. 
For further discus- 
sion, see "Primary Keys" in the DBBUILD chapter of 
this manual. 
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VIII. 
INFORMIX Reserved 'lords 


Do not use these words as file or field names. 


---' ., 


A 


access 
add 
after 
alias 
all 
allow 
allowing 
and 
ascending 
ass 
assign 
att 
attribute 
attributes 
audit 
average 
avg 


B 


before 
begin 
blanks 
bottom 
by 
bye 


c 


call 
char 
character 
clipped 
comments 
comp 
composite 
. count 
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database 
date 
db 
defaul t 
define 
delete 
descending 
do 
dominant 
double 
downshift 
duplicates 
dups 


E 


edate 
else 
end 
erase 
every 
ex 
execute 


F 


field 
file 
find 
first 
float 
for 
format 
from 
function 


G 


group 


H 


header 
headings 
help 


I 
if 
include 
index 
inputinsert 
instructions 
int 
integer 
intersect 
into 


J 


join 
joining 


L 


last 
left 
len 
length 
let 
line 
lineno 
lines 
load 
location 
lock 
long . 
lookup 
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M 
prompt 
time 
pUblic 
to 
margin 
today 
master 
top 
matches 
Q 
total 
max 
trai 1 
min 
queryclear 
trailer 
minus 
tra i ling 
money 
tuple 
R 
type 


N 
read 
record 
U 
next 
recover 
noentry 
reI 
union 
none 
relation 
unique 
noprompt 
rename 
unload 
not 
report 
unlock 
noupdate 
required 
update 
reverse 
upshift 
right 
user 
0 
run 
using 


ot 
on 
S 
V 
optional 
or 
aame 
variable 
output 
schema 
verify 
screen 
sel 
p 
select 
W 


serial 
page 
skip 
.. 
where 


pageno 
sort 
while 
para. 
space 
wi thout 
pause 
spacea 
percent 
start 


perm 
statua 
Y 
permiasion 
step 
peraissiona 
atop 
ydate 
pipe 
previous 
primary 
T 
Z 
print 
printer 
then 
zerotHl 
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I. 
Introduction 


DBBUILD is the data description language that 
you use to create new databases, add files to them, 
and change the structure of existing files. 
For 
each database file you want to create, you write and 
then compile a DBBUILD program called a "schema." 
The schema specifies the name of the database that 
the file belongs to, the name of the file, and the 
names and other defining information for each of the 
fields in the file. 


When you compile a schema, DBBUILD creates the 
operating system files that hold 


• 
Data 


• 
Indexes 


• 
The database dictionary (one for each database) 


On UNIX systems that do not automatically han- 
dle concurrency control, a .lok file that allows IN- 
FORMIX to lock database files and records is also 
created. 


Each database file is represented by two 
operating system files, one to hold the data and 
another to hold the indexes. 
For both of these 
files, 
DBBUILD uses the filename given in the schema 
(truncated if necessary to ten characters in UNIX 
versions of INFORMIX and eight characters in MS-DOS 
versions), adding the extension .dat for the data 
file and .idx for the index file. 
If the schema describes the first file of a da- 
tabase, DBBUILD creates an operating system file to 
hold the database dictionary. 
DBBUILD names this 
file,' using the database name given in the schema 
(truncated if necessary) and the extension charac- 
ters .dbd, for database dictionary. 


These names are designed to conform to the 
operating system's limits on the lengths of 
filenames. 
DBBUILD uses the first ten characters 
(under UNIX) or the first eight characters (MS-DOS) 
to determine the uniqueness of filenames. 
However, 
the names you give in the schema may be up to 50 
characters long. 


Field names can also be 50 characters long. 
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The entire field name is used to determine unique- 
ness. 
Both field and file names must be at least 
two characters long. 


Every field name and file name in the database 
must be unique. 


The number of files and fields is limited only 
by the addressable main memory of a process in the 
computer, which is usually an operating system limi- 
tation. 
The maximum size of both a field and a 
record is 2048 bytes (characters). 


Throughout the examples in this chapter, the 
stores database shown in Figure 1 is assumed. 


Figures 2 and 3 show the schemas for the 
customers and orders files in the stores database. 


customers file 


cname 


Brooks, B. 
Field, 
W. 


Robin, R. 
Hart, 
W. 


Court, S. 
English, 
D. 


orders file 


oname 


Brooks, B. 
Brooks, 
B. 
Robin, R. 
Hart, W. 
Robin, R. 
Court, 
S. 
Court, S. 
English, 
D. 
English, 
D. 


address 


7 Apple Rd. 
43 Cherry Ln. 
12 Heather Ct. 
65 Lark Rd. 
56 Blossom Rd. 
82 Alpine Rd. 


item 


Work Bench 
Saw 
Work Bench 
File 
Hammer 
Saw 
File 
File 
Hammer 


balance 


10.50 
0.00 
23.45 
43.00 
0.00 
0.00 


quantity 


5 
1 
3 
3 
8 
3 
5 
1 
2 


Figure 1. 
The stores database 
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database stores 


file customers 


field cname 
field address 
field balance 


end 


type character 
type character 
type double 


length 15 
length 15 
index dups 
index dups 
index dups 


Figure 2. 
The schema for the customers file. 


database stores 


file orders 


field oname 
type character 
field item 
type character 
field quantity type integer 


end 


length 15 
length 15 
index dups 
index dups 
index dUps 


Figure 3. 
The schema for the orders file. 
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II. 
Definition of the DBBUILD Language 


Like programs written in any other computer 
language, DBBUILD programs have a certain syntax and 
structure. 
An explanation of that syntax and struc- 
ture, with examples, follows. 


II.A. 
Identifiers 


Identifier"s, such as filenames and field names, 
can be composed of any combination of letters, 
(A- 
Z), digits, (0-9), and symbols, with the following 
exceptions. 


$ 
In UNIX versions of INFORMIX, you cannot use 
any of the following symbols: 


- * ? 
( 
] $ 
! 
\ 
/ 
{ 
} 


In MS-DOS versions of INFORMIX, you cannot use: 
• < > \ I { } 


Identifiers must begin with a letter and can be 
2-50 characters long. 


Uppercase and lowercase, although tolerated, 
are not significant in comparisons. 
All identifiers 
are made lowercase when stored in the database dic- 
tionary. 
Thus, you cannot assign identifiers that 
differ only in case. 


You cannot use any of INFORMIX's reserved words 
(listed in Section VIII of the Introduction) as 
identifiers. 
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II.B. 
Constants 


The only constant in the DBBUILD language is 
the integer, which is used to describe the length of 
CHARACTER fields. 


II.C. 
Comments 


.' 


You can 
of a schema. 
daries. 
Use 
comments. 


include comments anywhere in the text 
Comments can cross over line boun- 
the curly brackets { and } to delimit 


II. D. 
Keywords 


You can type DBBUILD's keywords in any mixture 
of uppercase and lowercase. 
The keywords and their 
usage are as follows. 


DATABASE database_name 


The DATABASE keyword identifies the database to 
which the file being created will belong. 
The DATA- 
BASE keyword and a database name are mandatory. 


FILE file name 


The 
created. 
datory. 
tabase. 


FILE keyword names the database file being 
The FILE'keyword and a file name are man- 
The file name must be unique within the da- 


FIELD field_name 


The FIELD keyword is required for every field 
being defined in the database file. 
Field names 
must be unique not only within the database file, 
but throughout the entire database. 
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TYPE type_indicator 


The TYPE keyword is required for every field. 
The type indicator must be one of these keywords: 
CHARACTER, 
INTEGER, 
DOUBLE, 
LONG, 
FLOAT, SERIAL, 
DATE, EDATE, 
YDATE, 
MONEY, or COMPOSITE. 


TYPE CHARACTER 


CHARACTER fields can contain letters, numbers, 
and symbols. 
If the TYPE CHARACTER phrase is used, 
it must be followed by a length specification. 
TYPE 
CHARACTER can be abbreviated as TYPE CHAR. 


LENGTH 10 


Character fields require a length specifica- 
tion. 
The length specification above indicates that 
the field is 10 characters long. 
Fields can be from 
1 to 2048 characters in length. 
The word LENGTH can 
be abbreviated as LEN or omitted. 


TYPE INTEGER 


INTEGER fields contain whole numbers (numbers 
without a fractional part) between -32,768 and 
+32,767. 
INTEGER can be abbreviated as INT. 
In- 
teger fields occupy two bytes of space. 


TYPE LONG 


LONG fields contain integers between 
-2,147,483,648 and +2,147,483,647 and occupy four 
bytes of space. 


TYPE FLOAT 


FLOAT fields contain single precision floating 
point numbers. 
Seven significant digits are allowed 
on either side of the decimal. 
A float number occu- 
pies four bytes of space in the record. 


TYPE DOUBLE 


DOUBLE fields contain signed floating point 
numbers. 
Fourteen significant digits are allowed on 
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either side of the decimal. 
Specifically, the dou- 
ble precision floating point number of the C pro- 
gramming language is used. 
A double number occuoies 
eight bytes of space in the record. 


TYPE SERIAL 


SERIAL fields are assigned sequential serial 
numbers by INFORMIX. 
SERIAL data is stored in a 
LONG field. 
If you do not indicate a starting 
number, the first record is assigned serial number 
1. 
To begin the sequence at a different starting 
point, specify "start" and the first desired serial 
number, for example, "start 100". 
You can specify a 
negative number. 


INFORMIX assigns serial numbers after you indi- 
cate that a record is complete. 
To assure serial 
number integrity, 
INFORMIX does not allow you to 
change the value in a SERIAL field. 
SERIAL fields 
can be joined with LONG fields as well as with 
othe~ 


SERIAL fields. 


You can specify only one SERIAL field in a da- 
tabase file. 
If you specify a SERIAL 
fiel~, it be- 
comes the PRIMARY KEY for the file unless you speci- 
fy another PRIMARY KEY. 


field empno 
type serial start 10000 {begin at 10a01} 


field deptno type serial 
{begin at 1} 


TYPE DATE 


DATE fields contain dates in the format 
"mm/dd/yy" where 
mm represents the month, dd the 
date, and yy the year. 
Available variations are 
EDATE "dd/mm/yy" and YDATE "yy/mm/dd". 
Dates are 
stored as LONG integers representing the number of 
days since January 1, 1900. 


You can sort fields of these three types in ACE 
and INFORMER. 
You can perform arithmetic functions 
on DATE fields with day resolution and compare two 
DATE fields chronologically. 
Date arithmetic is 
particularly use£ul in 30-60-90 day aging of ac- 
counts in financial applications and in calendar 
"tickler" file applications. 
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TYPE MONEY 


MONEY fields· are stored as double precision 
floating point numbers (in cents). 
Money entries 
are formatted in the typical $000.00 fashion and 
computations are exact to $.01. 


TYPE COMPOSITE 


COMPOSITE fields combine two to eight previously 
defined fields. 
For example, an "aisle" and a 
"shelf" field can be formed into the composite field 
"position". 
Name component fields, 
separated by 
commas, following the data type, as shown below. 
You can abbreviate COMPOSITE as COMPo 


database inventory 
file stock 


field aisle 
field shelf 
field position 


end 


II.E. 
INDEXING 


type integer 
type integer 
type compo si te 
aisle, shelf 


You can index as many fields as you like when 
you create a database file. 
Put the word "index" in 
the schema after the field definition. 
For example: 


field cname 
type character 
length 25 
index 


INFORMIX assumes that indexed fields contain 
unique entries unless the "index" specification is 
followed by the word "dups", indicating that dupli- 
cate entries are allowed. 
Examples of both appear 
later in this section. 
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PRIMARY KEYS 


Many INFORMIX programs depend on being able to 
read records by at least one uniquely indexed field, 
referred to as a "primary key." 


A primary key is a unique identifier of the 
record. 
For example, an "employee number field" 
might be the primary key identifying employee 
records. 


Specifying a primary key is optional. 
If you 
do not specify one, INFORMIX automatically puts an 
invisible unique 4-byte field on the front of each 
record. 
This field acts as a hidden primary key. 


If you are using INFORMIX with programs written 
in COBOL or other languages and the default primary 
key causes compatibility problems, you can specify 
another field as a primary key. 
The primary key 
'must be a non-duplicating field identified as an in- 
dex. 
It can be any type of field, including a COM- 
POSITE field. 
You can assign only one primary key 
in a database file. 


If you do not specify a primary key but do in- 
clude a serial field in your file, the serial field 
becomes the primary key and INFORMIX does not create 
a hidden primary key. 


field empno 
type serial 
index 
{dups not allowed} 
field edeptno type integer index dups {dups allowed} 
field edeptmn type integer index 
{dups not allowed} 


You can use DBSTATUS commands to add and remove 
indexes. 
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II.F. 
Modifying the Operating System Environment 


LOCATION 


You can use the LOCATION option to spread a da- 
tabase across a number of directories, file systems, 
disks, or volumes. 
The LOCATION option simplifies 
access to INFORMIX files via C-ISAM, COBOL, or other 
languages. 


To use the LOCATION option, put the keyword LO- 
CATION, followed by an operating system pathname en- 
closed in quotation marks, in the schema after the 
DATABASE and FILE statements. 


database realty 
file agents 


location "/z/charles/rlbase/age" {under UNIX} 
{or} 
location "c:charles/rlbase/age" 
{under MS-DOS} 


When this schema is compiled, the realty data- 
base dictionary is created in the current directory. 
The data and index files for agents are created in 
the directory /z/charles/rlbase under UNIX or in 
charles/rlbase on volume C under MS-DOS. 
The rlbase 
directory must exist before you compile the schema. 
The data file is called age.dat and the index file 
is called age.idx, as specified by the LOCATION 
sta tement. 


DBPATH 


Usually, 
INFORMIX assumes that your database 
dictionary is on the current device and in the 
current directory. 
With the DBPATH environment 
variable, you can specify other search paths to be 
used in locating the database dictionary. 
Thus, 
DBPATH allows you to run INFORMIX in a directory 
other than the one in which the database dictionary 
resides. 
DBPATH only affects programs in the Main 
Menu--not DBBUILD, FORMBUILD, or ACEPREP. 


DBPATH must be set by an operating system com- 
mand before you call INFORMIX programs or the Main 
Menu. 
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In UNIX systems, you can set the DBPATH vari- 
able either before an INFORMIX session or permanent- 
ly (i.e., in the .login or .profile file). 
In the C 
she11, use the "se tenv" command. 
For example: 


% setenv DBPATH :/z!john!realty 


The colon preceding the path instructs UNIX to 
search the current directory before searching the 
specified directory. 
You can specify a series of 
path descriptions. 


The comparable Bourne shell command is 


DBPATH=:/z/john/realty 
export DBPATH 


In MS-DOS systems, a comparable command would 
be 


A> set DBPATH=;c:\mydir 


This command instructs INFORMIX to search for 
database dictionaries in the current directory (sig- 
nified by the semicolon) and then in the directory 
MYDIR on volume C. 


PATH 


Setting or changing the PATH variable may af- 
fect other system commands in addition to INFORMIX 
commands. 


Usually, 
INFORMIX programs are assumed to be on 
the current device and in the current directory 
(under 
MS~DOS) or in /usr/bin (under UNIX). 
With 
PATH, you can specify other search paths to be used 
in locating INFORMIX programs. 


PATH is set by an operating system command. 


In UNIX systems, you can change the PATH vari- 
able either before an INFORMIX session or permanent- 
ly in the .login or .profile file. 
In the C shell, 
use the "setenv" command. 
For example: 


% setenv PATH :/z!john 


The colon preceding the path instructs UNIX to 
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search the current directory before moving to the 
specified directory. 
You can include a series of 
paths. 


The comparable Bourne shell command is 


PATH=: /z/ john 
export PATH 


In MS-DOS versions, use the PATH command. 
For 
example, if you put INFORMIX programs in the direc- 
tory mydir on volume C, give the command 


A> PATH ;c:\mydir 


This path (and any others you specify) will be 
searched by the INFORMIX Master Menu when you call 
the program. 
You need not include the semicolon 
(indicating the current directory) in the 
PATH list, 
since MS-DOS always searches the current directory. 


DBTEMP 


The DBTEMP variable allows you to specify the 
location of temporary files created by INFORMER or 
ACE. 
If you do not set DBTEMP, temporary files are 
placed in the /tmp directory in UNIX systems and in 
the current directory under MS-DOS. 


For more on DBTEMP, see "Changing the Location 
of Temporary Files Using DBTEMP" in the INFORMER 
chapter of this manual. 


II~G. 
User 
~ccess Privileges 


In UNIX versions of INFORMIX, you can set user 
access privileges. 
MS-DOS versions of INFORMIX do 


not support this feature. 


UNIX permissions supersede INFORMIX permis- 
sions. 
UNIX read permission allows you to view IN- 
FORMIX files. 
UNIX write permission is required in 
order to use INFORMIX programs which update, delete, 
or add data. 
In addition to the proper access per- 
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missions for the database files, you must have prop- 
er access permissions for the directories containing 
the files. 


INFORMIX permissions act in addition to the 
UNIX read and write permissions. 
You can set INFOR- 
MIX permissions at either the file or the field lev- 
el. 


INFORMIX file level permissions allow you to 
read, add, update, and delete records and to use the 
following commands that modify database structure: 
DBBUILD -r, the INFORMER commands ADDINDEX, 
DELETE 
INDEX, and the 
DBSTATUS commands ADD INDEX, 
DELETE 
INDEX, 
ERASE DATABASE, 
ERASE FILE, ERASE AUDIT, 
RENAME FIELD, 
START AUDIT, 
STOP AUDIT, 
RECOVER FILE, 
LOAD, and LOAD ASCII. 


Field level permissions allow you to read and 
update individual fields. 


To specify the user or group of users with 
designated permission, use an operating system user 
name or group name (as defined by the files 
/ete/passvd and fete/group respectively) or another 
user designation (such as "public"). 


The INFORMIX permissions and their applications 
are: 


ACCESS 


all 
none 
read 
update 


add 
delete 
control 


APPLICATION 


file, field 
file, field 
file, field 
file, field 


file, field 
file 
file 


EFFECT 


full access 
no access 
able to read data 
able to change 
eXisting data 
able to add new data 


~ble to remove records 
able to restructure 
database files 


Once you apply restrictions to a database file, 
all fields in the file are affected unless field 
permissions are specifically· granted. 
Limitations 
imposed on one database file do not affect access to 
other files in the database. 
Without read permis- 
sion, no other access to a file (or field) is possi- 
ble. 
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The following example shows how permissions are 
specified in a schema. 


database company 


file employees 


field emp no 
fie ld last name 
field first name 
field dept no 
field dept-name 
field salary 
field date hire 


permissions 


file 
file 
fie ld salary 
field salary 


end 


pUblic 
user john 
public 
group group1 


access read add 
updat~ 


access delete 
access none 
access all 


In the example above, 
"pub lic" refer s to all 
users of the system. 
"john" is the operating system 
login name for an individual system user. 
"group1" 
is the name of an operating system group of users. 


The first file permission allows all users 
(public) access to the entire file for read,· update, 
and add, but not delete. 
The second file instruc- 
tion permits only john to delete records. 
This set 
of permissions prohibits any other user from delet- 
ing records. 


The first field permission denies all users any 
kind of access to the 
SALARY field. 
This field will 
be omitted from ENTER2 screens and left blank in 
PERFORM screens. 
The final 
~ermission allows users 
in "group1" read and update privileges to salary 
data. 


"Permissions" in the above example could be ab- 
breviated as "permission" 
o~ as "perm". 


To change the permissions for a database, edit 
the schema to reflect the new permissions and then 
recompile it ~sing the DBBUILD command. 
You need 
not use the -r flag. 
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III. 
Sample Run 


You create a DBBUILD schema using an operating 
system text editor. 
Once the schema file has been 
written, compile it with the command DBBUILD. 


For example, to compile the file called 
custschem, give the command: 


%dbbuild custschem 


If the compilatien is successful, INFORMIX 
creates the operating system files for the database 
file described in the schema. 
The operating system 
file for the data is named filename.dat (where 
filename is the name specified in the schema file). 
The operating system file that contains indexes is 
named filename.idx. 


In addition, if the database file is the first 
in the database, an operating system file for the 
database dictionary is also created. 
It is called 
databasename.dbd (where databasenaae is the name 
specified in the schema file). 


On some UNIX systems, 
INFORMIX also creates a 
.1ok file. 
If the compilation is unsuccessful, 
DBBUILD 
displays an error message and creates an operating 
system file that contains an error listing. 
(The 
error numbers refer to the DBBUILD appendix.) 
This 
file is given the name of the schema file and the 
extension .err. 


In the example that follows, an operating sys- 
tem file named badschem contains the keyword "file" 
spelled "filen". 
DBBUILD generates an error file 
called badschem.err. 
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~ cat badschem 


database stores 
f1len customers 


field cname 
!1eld address 
!1eld balance 


end 


type character 
type character 
type double 


length 15 
length 15 
index 
index dups 
index dups 


~ dbbuild badschem 


DBBUILD Data Description Language Compiler 
INFORMIX version 3.2 
Copyright (C) 1981, 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-000001 


The file "badschem" will now be compiled. 


The compilation was not successful. 
Errors found: 1. 
The file "badschem.err" has been written. 


Program over. 


~ cat badschem.err 


. database stores 
filen customer s 


A grammatical error has been found on line 3, character 1. 
The construct is not understandable in its context. 
See error number 2018. 


field cname 
!1e Id addre ss 
field balance 


end 


type characte r 
type character 
type double 


length 15 
length 15 
index 
index dups 
index dups 


Figure 4. 


INFORMIX 


You must change the word "filen" to "file". 
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IV. 
Changing the Structure of a Database 


You change the structure of a database file in 
two steps. 
First, edit the schema to reflect the 
new structure. 
Then re-compile the edited schema 
file. 


For example, the schema shown below is an edit- 
ed version of the schema in Figure 2. 
It has been 
changed to reflect a longer field length for the 
field cname and the addition of a new field called 
city. 


database stores 
file customers 


field cname 
field address 
field city 
field balance 


end 


type character length 25 
type character length 15 
type character length 20 
type dolible 


index 
index dups 


index dups 


To re-compile this changed schema file use the 
-r, or rebuild, flag of the DBBUILD compiler. 
(In 
MS-DOS versions of INFORMIX, you must enter the re- 
build flag as a lowercase "r".) 


DBBUILD asks you to verify the new structure 
before it actually changes the database. 
At this 
point, you may choose to stop the rebuild. 


An example is shown in Figure 5. 


When you add new CHARACTER fields, they are 
initialized with blanks. 
Fields of any of the 
arithmetic data types are initialized with zeros. 
When a field is expanded, the new characters are 
blanks. 
If a field is shrunk, any characters in the 
part being taken away are lost forever. 


If you change a CHARACTER field to an arithmet- 
ic type field, 
DBBUILD may print an error message 
indicating that one or more o£ the records contains 
characters other than digits. 
If you change from an arithmetic type field to 
a CHARACTER field, make the new CHARACTER field long 
enough to hold the already existing entries, or 
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DBBUILD will display a field overflow error message. 


DBBUILD automatically locks a file while it is 
being modified. 
It replaces any indexes that exist- 
ed before the rebuilding. 


Any existing audit trails become useless be- 
cause the structure of the file has changed, while 
the structure of the previously recorded audit trail 
records has not. 
You must restart audit trails 
(from DBSTATUS) after you re-compile a schema. 


To change the name of a field, 
use the DBSTATUS 
RENAME FIELD command and then modify the schema to 
reflect the change. 
If you try to change a field 
name without using the 
RENAME FIELD command first, 
DBBUILD interprets the change as a deletion of an 
old field and an addition of a new one. 
The data in 
the field will be lost. 


Caution: 
than one file 
of the files. 
time. 


INFORMIX 


Do not simultaneously rebuild more 
in a database or you will corrupt one 
You must rebuild the files one at a 
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~ dbbuild -r custschem 


DBBUILD Data Description Language Compiler 
INFORMIX version 3.2 
Copyright (C) 1981, 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-000001 


The tile wcustschemw will now be compiled. 


The tollowing table describes the changes specified in the 
schema tile wcustschemw• 
Review this table carefully to be 
absolutely certain that the changes described here are the changes 
you want made to the file wcustomers w• 


Type of Change 
Field 
------Old------ 
Type 
Length 
------New------ 
Type 
Length 


new length 
add new fie ld 
cname 
city 


character 
15 
character 
character 


25 
20 


Type carriage return to continue. 
{abort by typing delete} 


WARNING: 
Any audit trails for the file wcustomers w will become 
unusable and must be restarted after this REBUILD. 


Enter the letter 'y' if you wish to continue with the REBUILD 
of the file wcustomersw• 
) y 


{Typing 'n' will abort.} 
{There will be a pause while the file wcustomers" is reconstructed.} 


T~ compilation was successful. 
The file that holds the 
dictionary tor the database "storesw has been created or updated. 


Program over. 


Figure 5. 
Recompiling the customers file. 
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v. 
Appendix - Error Messages 


error 2001: 


The identifier specified is a reserved keyword used 
in other programs of INFORMIX. 


error 2005: 


With the addition of this field, 
the record would 
exceed the maximum allowed record length. 
The max- 
imum is 2048 bytes. 


error 2007: 


The file specified has been defined previously. 
This may be because the first ten characters (UNIX) 
or the first eight characters (MS-DOS) of the file 
name are used to determine the uniqueness of the 
name. 


error 2008: 


The file specified could not be opened for reading. 


error 2009: 


The database dictionary file specified is incompati- 
ble with this version of INFORMIX. 
This file should 
be removed and built. 


error 2010: 


The database dictionary file 
specif~ed could not be 
created. 


error 2011: 


The database dictionary file specified could not be 
wri tten. 
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error 2012: 


A database or file of the same name exists already 
in this directory. 
Since only the first ten (UNIX) 
or eight (MS-DOS) characters of the database name 
are used it could be that only these characters are 
the same. 


error 2013: 


The file specified could not be opened for writing. 


error 2014: 


There were an incorrect number of arguments on the 
operating system command line. 
At least one (1) ar- 
gument is expected. 


error 2015: 


An open comment symbol, 
{, was found inside an al- 
ready open comment. 
This could be due -to a failure 
to close the previously opened comment. 


error 2016: 


A comment has been opened, but not closed. 


error 2018: 


A grammatical error has been found. 
The construct 
is not understandable in its context. 


error 2019: 


This integer exceeds the maximum size allowed. 


error 2021: 


The length specification for this field must be one 
or greater. 
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error 2022: 


This identifier exceeds the maximum length for iden- 
tifiers which is 50 characters. 


error 2023: 


This quoted string exceeds the maximum length for 
quoted strings which is 50 characters. 


error 2025: 


The comment close symbol, 
}, has been found even 
though no comment has been opened. 


error 2026: 


File names must be at least two characters in 
length. 


error 2027: 


An illegal (invisible, control) character has been 
found. 
It has been replaced by a blank in the list- 
ing, but it is still in the source (input) file, and 
should be removed before attempting to compile 
again. 


error 2028: 


Field names must be at least two characters in 
length. 


error 2029: 


The field specified has been defined previously. 


error 2030: 


A typographical error has been found. 
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error 2032: 


The number above could not be successfully converted 
to either an INTEGER or a DOUBLE. 


error 2033: 


The database to be rebuilt could not be opened. 
This is probably because it does not exist. 


error 2035: 


An ASCII to numeric conversion error has occurred. 
The field specified holds an ASCII value which is 
not convertible to a binary numeric value. 


error 2036: 


A number found in the field specified is too large 
to fit within the length specified for it within the 
new schema. 


error 2037: 


The temporary file used for the restructuring of the 
file specified could not be created. 
Be sure that 
you have the proper access privileges in the current 
directory so that this temporary file may be creat- 
ed. 


error 2038: 


The ISAM files which hold the temporary file could 
not be buHt. 


error 2039: 


The REBUILD was aborted by a REBUILD subroutine 
failure. 


error 2040: 


The source file name specified exceeds the maximum 
length of 10 characters. 
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error 2041: 


The source file specified cannot be opened. 
This is 
probably because the file does not exist. 


error 2042: 


An error occurred when an attempt was made to unlink 
the error file specified. 


error 2043: 


The database dictionary specified could not be 
created. 
This'is probably because the user does not 
have permission to create files in this directory. 


error 2044: 


A file needed by DBBUILD is locked by another user. 


error 2045: 


A file needed by DBBUILD is exclusively locked by 
another user. 


error 2046: 


An error has occurred during the addition of an in- 
dex. 


error 2047: 


The field specified as type specified contains a 
value which cannot be properly converted to type 
specified. 


error 2048: 


A memory allocation error has occurred. 


error 2049: 


The attribute name specified is not part of the file 
definition, and is used as part of the composite key 
specified. 
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error 2050: 


The composite key specified has more parts than al- 
lowed. 


error 2051: 


Two fields have been designated as primary keys. 


error 2052: 


Two fields have been designated as serial keys. 


error 2053: 


Interrupt received. 


error 2054: 


The file specified does not exist, so it cannot be 
rebuil t. 


error 2055: 


Field used in permission list is not part of the 
current record. 


error 2056: 


User specified is not known. 


error 2057: 


Group specified is not known. 


error 2058: 


Permission to do this operation on the file speci- 
fied is not granted because you do not have CONTROL 
access to the file. 
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I. 
Introduction 


PERFORM and FORMBUILD, its screen compiler, are 


the INFORMIX facilities for creating custom-designed 
data entry screens and for performing simple 
queries. 


Like ENTER2, 
PERFORM allows you to add, delete, 
find, and update records interactively. 
However, 
there are significant differences between ENTER2 and 
PERFORM. 


ENTER2 is screen-oriented, but it does not pro- 


vide a facility for the design of screen forms. 
When you run ENTER2, the program constructs a simple 
screen based on the information in the data 
dictionary and displays it for data entry and very 
simple queries. 
On an ENTER2 screen, one field is 
displayed on each line. 
If there are more fields 
than can fit on one screen, you can page through the 
multiple screens. 


Through the default option of FORMBUILD, PER- 
FORM can also construct simple data entry screens. 
In addition, 
PERFORM allows you to design your own 
screen forms. 
On a custom-designed form, 
you can 
place fields anywhere on the screen, with whatever 
labels or titles you like. 
If there is more data 
than can fit on a screen, you can design multiple- 
screen forms. 


ENTER2 can display data from only one file at a 
time. 
PERFORM lets you design forms that contain 
fields from more than one file. 
The relational 
"join" operation is used to describe how the files 
cross-reference each other. 


PERFORM can also validate data, checking wheth- 


er entries fall within a specified range or meet 
other criteria. 
PERFORM provides range checks and 


other simple analysis of field entries, as well as 
more sophisticated checking such as table lookup, 
mandatory entry, and verification. 
Fields may also 
be assigned default values, right- or left- 
justified, and upper- or lowercase adjusted. 


Sophisticated browsing capabilities and many 


query facilities have been incorporated into PER- 
FORM. 
You can select a record or group of records 
from the database using the relational operators (as 
with INFORMER) or ranges of values. 
Any records 


.r 
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found can be modified or deleted. 
New records can 
also be added. 
PERFORM automatically maintains 
lists of the records most recently added and re- 
trieved. 


PERFORM allows users and system designers to 
define screen forms and provides an easy-to-use in- 
teractive program for working with data through 
these forms. 
Once you learn how to design your own 
screen forms, 
you will probably use PERFORM more 
often than any other INFORMIX program. 


Factors Limiting Form Size 


The maximum size of a PERFORM form depends on 
the size of the data area in your computer's main 
memory. 
.For example, a computer with a 40-Kbyte 
data area will allow on the order of 75 data fields 
per form and a 64-Kbyte data area will allow about 
150 data fields per form. 
Machines with larger data 
areas will allow larger forms. 


The amount of space a form occupies is deter- 
mined by the size of the database dictionary (for a 
64-Kbyte machine, the total number of fields in the 
database should not exceed approximately 300), the 
overall size of the form description (number of 
fields in the form, length of field 
names~ display 
field labels, comments, etc.), and the number of 
joins (lookups) in the form. 


If your form is too large, you will receive one 
of the following messages: 2988 (FORMBUILD has run 
out of memory) or 3680 (PERFORM has run out of 
memory). 
You can also receive a message, such as 
2920, 2970, or 2978, that indicate a lack of an in- 
dex or a type mismatch. 
These messages may be re- 
turned by FORMBUILD when it cannot read the entire 
database dictionary. 
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II. 
Defining Screen Forms 


Data entry forms for 
PERFORM are created with 
the FORMBUILD command. 
FORMBUILD can create both 
simple default and custom-designed forms. 


II.A. 
Creating Default Forms 


You can create a simple form file by running 
FORMBUILD with the default (-d) option. 
The default 
option automatically creates and compiles a default 
form and form specification file based on your 
answers to a series of questions. 
You can use a 
text editor to modify the default form specification 
file. 


To create a default form file, your working 
directory must contain the database schema and its 
related files. 
To build a default form enter: 


% formbuild -d 


Under MS-DOS the -d option must be lowercase. 


FORMBUILD requests a name for the form specifi- 
cation file 
(up to ten characters long under UNIX, 
eight characters under MS-DOS), the name of the da- 
tabase, and the file or files you want to include in 
the form. 


You can also give the command in this form: 


~ formbuild -d [form name] [database name] [file1] ••• [filen] 


Once FORMBUILD has names for the form to create 
and the database and files from which to create the 
form, it creates a form specification file with one 
page for each file you designate. 


For example, you might create a default list- 
ings form named dlistings to use with the demonstra- 
tion database: 
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• formbu1ld -d 


FORHBUILD Data Entry Form Bu1lder 
INFORHIX vars10n 3.2 


Copyr1ght (Cl 1981, 1982, 1983 Relat10nal Database Systems, Inc. 
Software Ser1al Number RDS-000001 


Enter des1red name for the form: d11st1ngs 
Enter the name of the database used by the form: 
realty 


You v1ll nov enter the namas of the database f1les vh1ch 
v1ll appear on the form. 
You may enter a max1mum of 8 
f1le names. 
Enter a carriage return alone to term1nate 
the 
seq~n~. 


Enter a file nama: 
l1st1ngs 


Entar a f1le nama: 


The f1le "d11at1ngs" v1ll nov be comp1led. 


The form comp1lat10n vaa successful. 


Program over. 


In addition to the form specification file, 
FORMBUILD with the -d option creates an operating 
system file that contains the compiled form. 
FORM- 
BUILD gives the form specification file the name you 
entered in response to the prompt for a form name. 
It gives the compiled version that same name with 
the extension .trm. 
The example run of FORMBUILD 
would create files named dlistings and 
dlistings.trm. 


II.B. 
Designing Customized Forms 


To build a customized screen form, you create a 
form specification file and then compile it with 
FORMBUILD. 
The simplest form specification file 
identifies the database, shows the layout of fields 
on the form (called "display fields"), 
and identi- 
fies the correspondence between display fields and 
database fields. 


FORMBUILD also enables you to define specific 
characteristics -- called attributes -- for each 
field. 
For example, you can specify that PERFORM 
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Display a message when the cursor moves into a 
particular field 


Accept only certain values as input to a par- 
ticular field 


8 
Right-justify the data in a particular field 


To design your own screen form, 
use a text edi- 
tor to create a form specification file. 
Then com- 
pile it with FORMBUILD. 
This section describes how 


to specify the form file. 


The first few examples are based on the real 
estate example shown in the ENTER2 manual. 
The 
schema for the real estate database is shown for 
reference in Figure 1. 
It is not part of the form. 


A screen form for this application could be 
designed using the form specification file shown in 
Figure 2. 
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database realty 


file listings 


field listing_number 
type integer 
field address 
type character 
length 20 
field city 
type character 
length 20 
field footage 
type integer 
field bedrooms 
type integer 
field baths 
type integer 
field lot size 
type double 
field cornel' lot 
type character 
length 
field schools 
type character 
length 
field asking_price 
type money 
field sales price 
type money 
field broker 
' type character 
length 15 index dups 
field listing_note1 
type character 
length 45 


end 


database realty 


file agents 


field agent_number 
type integer 
field agent_name 
type character 
length 15 index 
field agent_address 
type character 
length 20 
field agent_city 
type character 
length 10 
field agent zip code 
type long 
field agen(yhone 
type character 
length 8 
field agent_salary 
type money 


end 


Figure 1. The schemas for the realty database. 


.' 
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database real ty 


screen 
{ 


Real Estate Listings for Single Family Dwellings 
in Santa Clsra County, California 


agent name [list1 


listing number 
[list2 ] 
street address 
[ l1st3 
city 
[ l1st4 


footage 
[list5 
] 
bedrooms 
[l1st6 ] 
baths 
[ l1st7] 
lotsize 
[ l1st8 
corner 
[x] 
schools 
[y] 


asking price 
[list9 
] 


listing note 
[list11 
} 


end 
attributes 


aale pr ice 
[l1st10 


x 


l1st1 • broker; 
list2 • listing number, include. (1 to 30000), required; 
list3 • 
address~ required; 
list4 • city, required, default. "Santa Clara"; 
list5 • footage, include. (800 to 4000), 
comments. "Enter a number from 800 to 4000."; 
list6 • bedrooms, include. (1 to 15), 
comments 
E 
"Enter a number from 1 to 15."; 
l1st7 • baths; 
list8 • lot size, 
comments. "Enter acres or portions; .5 1s half an acre."; 
• corner lot, include. (Y,N,y,n), upshift; 
y 
• schools, include. (Y,N,y,n), upshift; 
list9 • asking price, required; 
list10 • sales-price; 
list11 
listing_note1[1,45]; 


end 


Figure 2. A form specification file (reaI1). 
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In Figure 2, the description of the screen it- 
self appears between the the curly bracket charac- 
ters { and }. 


This screen description uses only one database 
file. 
However, a single form can contain data from 
several files. 
The files must all be part of the 
same database. 
The maximum number of files you can 
use on one form varies, and depends on your operat- 
ing system: 


e 
UNIX allows 20 open files, of which four are 
required by the operating system. 
This leaves 
16 for INFORMIX. 
Each INFORMIX file requires 
at least two operating system files, the .dat 
file for data and the .idx file for indexes. 
If you use only these two operating system 
files, 
INFORMIX can open 8 database files 
simultaneously. 


For each database file that has an audit trail, 
another operating system file is required. 
If 
you use audit trails on every file, 
INFORMIX 
can open 6 database files simultaneously. 
If you use a version of UNIX that does not au- 
tomatically handle concurrency control, INFOR- 
MIX creates a .1ok file for each database file. 
Under these versions of UNIX, 
INFORMIX can open 
6 database files simultaneously without audit 
trails or 4 database files with audit trails on 
every file. 


In addition, if your form includes lookup 
fields, together they count as a single file, 
which must be subtracted from the file limit. 


MS-DOS allows 20 open files, 
5 of which are re- 


quired by the operating system. 
This leaves 15 
for INFORMIX. 


Without audit trails, 
INFORMIX can open 7 data- 
base files simultaneously. 
With an audit trail 


on every file, 
INFORMIX can open 5 database 
files simultaneously. 


In addition, the use of lookup fields counts 
toward the file limit under MS-DOS. 
Each look- 
up field (or group of lookup fields from a sin- 
gle file) counts as one file toward the limits 
specified above. 
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Multiple-file forms will be discussed in detail 
in the Advanced Features section of this chapter. 


In the form specification file, each field that 
is to be included on the form is given a tag or la- 
bel in the square brackets that define the field's 
position. 
(You need not include every field in the 
form.) 
Field tags may be as short as one character 
in length and must begin with a letter. 


You associate the field tags with a database 
field name in the ATTRIBUTES section of a form 
specification file. 
The display field need not be 
the same length as the database field. 
A display 
field for character data can be shorter than the 
field's defined length. 


For numeric fields, 
the display field should be 
large enough for the largest number that might be 
displayed. 
If the display area for a numeric field 
is not long enough to hold the entire number that is 
entered, 
PERFORM fills the display field with aster- 
isks (*) to indicate the overflow. 


Portions of a character field can be displayed 
in a display field through subscripting. 
In the ex- 
ample below, the sixth through tenth characters in a 
field named partnumber are displayed. 


partnum = partnumber[6,10]; 


THE bank DATABASE 


Figure 3 shows the schemas for four files from 
the bank database. 
This is the database used as an 
example in the INFORMER chapter of this manual. 


Figure 4 shows a form specification file that 
combines data from the loan, customer, and employee 
files. 
It demonstrates a sophisticated customized 
screen design. 
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{LOAN SCHEMA} 


database bank 


file loan 


f'ield loan num 
field borr-num 
f'ield loan-date 
f'ield loan-type 
field loan-amt 
field primaryo!! 
f'ield secondoff 
f'ield term type 
f'ield rate- 


end 


type 
type 
type 
type 
type 
type 
type 
type 
type 


serial 
long 
date 
char 
money 
long 
long 
char 
float 


start 1000 index primary 
index dups 


length 15 


length 2 


{BANKCUST SCHEMA} 


database bank 


file bankcust 


field cust num 
type serial 
index 
field cust-Iname 
type char 
length 15 
f'ield cust-fname 
type char 
length 10 
field cust-addr 
type char 
length 20 
field cust::::city 
type char 
length 15 
field state 
type char 
length 2 
field zip 
type char 
length 5 
f'ield cust phone 
type char 
length 18 
field employer 
type char 
length 25 
field salary 
type money 


f'ie Id hired 
type date 
field co_app 
type long 


end 


Figure 3. Schemas for the bank database files • 
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{EMPLOYEE SCHEMA} 


database bank 


file employee 


field emp_num 
type serial 
index 
field emp lname 
type char 
length 15 
field emp-fname 
type char 
length 10 
field emp-addr 
type char 
length 20 
field emp-city 
type char 
length 15 
field emp-phone 
type char 
length 13 
field emp-hired 
type date 
field emp-dept 
type integer 
index dups 
field emp-title 
type char 
length 20 
field emp:salary 
type money 


end 


{DEPARTMENT SCHEMA} 


database bank 


file department 


field dept num 
field dept-name 
field dept:mngr 


end 


type integer 
index 
type char 
length 20 
type long 


Figure 3 con't. Schemas for the bank database files. 
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database bank 


screen 
{ 


LOAN INFORMATION 


Loan Number [lnum 1 
Borrower Number [bnum 1 
Borrower Name [fname 
1 [lname 


Primary Officer 
Number [off1 1 Name 
Secondary Officer Number [off2 1 Name 
[oname1 
[oname3 
[oname2 
[oname4 


Loan Type [ltype 
Loan Da te [ldate 


Iend 


attributes 


1 
Loan Amount [lamt 
Term Type [ttl 
Rate [rate 


lnum 
bnum 


fname 
lname 
off1 


off2 


ltype 
lamt 
ldate 
tt 


rate 


end 


a loan num; 
= *cust nurn 
= borr nurn, right, reverse, 
required, querycrear; 


• cust f'name; 
= cust-lname; 
• primaryoff, right, 
lookup oname1 = emp fname. 
oname2 = emp-lname joining *emp_num; 
• secondoff, right, 
- 
lookup oname3 = emp fname. 
oname4 = emp-lname joining *emp_num; 


• loan type; 
- 


• loan-amt. right; 
• loan-date; 
= term-type, include. (A1 to A5, 
B1 to B3. 
C1 to C7), 
comments. "A1-A5, B1-B3, C1-C7"; 


c rate, format 
c "NN.N'"; 


Figure 4. A form specification file. 
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II.C. 
Assigning Attributes 


The ATTRIBUTES section of a form specification 
file is used to indicate data checking, error mes- 
sages, default values, and other field characteris- 
tics. 
You can use any of the following attributes: 


a 
INCLUDE 


a 
COMMENTS 


a 
VERIFY 


a 
REQUIRED 


a 
LOOKUP 


a 
AUTONEXT 


a 
DEFAULT 


a 
NOUPDATE 


a 
NOENTRY 


a 
PICTURE 


a 
QUERYCLEAR 


a 
REVERSE 


a 
RIGHT 


a 
ZEROFILL 


a 
UPSHIFT 


a 
DOWNSHIFT 


a 
FORMAT 


.II. C.1 • 
INCLUDE 


INCLUDE causes PERFORM to check data before ac- 
cepting it. 
The list tag in the ATTRIBUTES section 
in Figure 2 is associated with the listing number 
field and is restricted to the range from 1 through 
30,000. 
If you enter a number not in this range, an 
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error message is printed at the bottom of the 
screen, the terminal beeps, and the cursor is repo- 
sitioned on the listing number field for correct 
data entry. 
- 


You can also specify: 


A range of alphabetic characters instead of 
numbers (in which case the characters are 
evaluated from left to right in ASCII order) 


• 
More than one range 


• 
Single number bounds 


• 
Ranges based on ASCII order that include other 
characters (by using quotation marks, e.g., 
"?") 


Here is an example of an INCLUDE statement with 
more than one range and with single number bounds: 


list1 = listing number, 
include-= (1 to 30000, 32000 to 32500, 
30505, 30507); 


This use of the INCLUDE attribute requires that 
the number entered fall into one of two ranges, or 
be exactly equal to two specific values: 30,505 or 
30,507. 
The ranges are 1 to 30,000, inclusive and 
32,000 to 32,500, inclusive. 


Data checking implies that some data entry is 
required. 
(See also the REQUIRED attribute, below.) 
If you anticipate that a user may not know what 
to enter in a field, you should provide the option 
of inserting blanks in a character field or a zero 
in an arithmetic field. 
A blank may be specified as 
an INCLUDE choice by enclosing a single blank space 
between double quotation marks in the include state- 
ment, as follows: 
tt = term_type" include = (A1 to A5, 
II II); 


To exclude blank entries, use 


include = ("!" to II-II) 
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You can use the 
COMMENTS attribute to display a 
message detailing acceptable input values. 


II.C.2. 
COMMENTS 


The COMMENTS attribute can be used to display a 
message at the bottom of a screen form when the cur- 
sor moves into a display field for data entry. 
For 
example: 


list1 
listing number, 
include-= (1 to 30000),' 
comments 
"Listing numbers range from 1 through 30,000"; 


II.C.3. 
VERIFY 


With the VERIFY attribute, you can request that 
PERFORM require that operators enter certain data 
twice in exactly the same way, before PERFORM ac- 
cepts the entry. 
For example: . 


f1 = order number, 
include 
= (1 to 49999), 
comments = 
"Order numbers are from 1 through 49999", 
verify; 


II.C.4. 
REQUIRED 


When you add records, all fields are initial- 
ized with default values. 
Normally, character 
fields default to blanks, numeric fields to 0, date 
fields to 00/00/00, and money fields to $0.00. 


However, if you are updating records, you can 
leave a field blank. 
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In addition, if you are adding records and 
clear an entry after making it, 
PERFORM will accept 
this blank entry. 
To assure that blanks or zeros 
will not be accepted, use INCLUDE. 


II.C.5. 
LOOKUP 


The "LOOKUP keyword causes PERFORM to cross- 
reference display fields to other fields, whether 
they are displayed or not. 
LOOKUP can cross- 
reference fields for verification purposes or to 
display data from one field in another. 


Here is an example of using LOOKUP for verifi- 
cation. 
The bank database contains a customer file 
and a loan file. 
Entries in the borr num field are 
verified as existing in the customer Tile before 
PERFORM accepts them. 
This means that only borrower 
numbers from existing customer records are valid en- 
tries. 


An asterisk (*) preceding the lookup field name 
indicates to PERFORM that the value that is entered 
into the borrower number field must already be in 
the customer file. 
The statement could read as fol- 
lows: 


num = borr_num, lookup from *cust_num; 


If the REQUIRED attribute is added for the 
borr num field, 
PERFORM will not accept a record 
without a valid entry in this field. 


num 
= borr_num, required, lookup from *cust_num; 


The statements above do not affect the PERFORM 
display until you attempt to enter invalid data. 


You can also display data from LOOKUP fields. 
Each loan record contains a borrower number and two 
loan officer numbers but no names. 
By looking up 
data from the customer and employee files, 
PERFORM 
can display the names of individuals whose numbers 
are entered. 


Here are the statements that look up the names: 
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num = *cust_num = borr_num, required; 


off1 
= primaryoff, lookup oname1 
= emp fname, 
oname2 = emp_lname from *emp_num; 


off2 
= secondoff, 
lookup oname3 
= emp fname, 
oname4 = emp_lname from *emp_num; 


! 
\ 


The first attribute line above joins the 
cust num field from the customer file with the 
borr-num field from the loan file and requires an 
entry-in ·the field. 
This entry must exist in the 
customer file to be accepted. 


The names of the loan officers are stored in 
the employee file. 
Using the LOOKUP keyword, 
PER- 
FORM can be instructed to find and display the ap- 
propriate officer name when the employee number is 
entered. 


The second two statements instruct PERFORM to 
look up the emp fname and emp Iname values from the 
employee file based on the values entered in the 
off1 and off2 display fields and to display them in 
the oname1, oname2, oname3, and oname4 display 
fields. 
The asterisks in. front of emp num indicate 
that only employee numbers that are present in the 
employee file will be accepted as valid entries for 
of'f'1 and off2. 


LOOKUP can also accommodate the need to find 
data located within a single file. 
If the customer 
file includes a field for a co-applicant number, you 
can instruct PERFORM to find the record of the co- 
applicant by joining the co-applicant and customer 
number fields. 
Once the fields have been joined, 
any desired information from that record can then be 
displayed using LOOKUP. 


conum = co app, 
lookup cfname = cust fname, 
clname 
= cust_Iname joining oust_num; 
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II.C.6. 
AUTONEXT 


The AUTONEXT attribute causes the cursor to ad- 
vance automatically to the next field when the 
current field is full, without waiting for the user 
to press RETURN. 
This feature is useful for enter- 
ing long texts that have been split into several 
fields appearing on consecutive line·s. 
For example, 
the listing note of Figure 2 could be placed on two 
lines: 


descl 
desc2 
listing note1[1,25], autonext; 
listing:note1[26,45]; 


This lets the operator enter the full length of the 
listing note1 text without pressing [RETURN] between 
the two-display fields. 
When the desel field is 
full, the cursor moves automatically to the begin- 
ning of the dese2 field. 


II.C.7. 
DEFAULT 


PERFORM automatically establishes a default 
value for every field on a screen form, based on the 
field type. 
When you add new records to a database, 
PERFORM displays the screen form with the following 
defaul t values: 


$ 
Character fields default to blanks 


$ 
Numeric field default to zero 


$ 
Date fields default to 00/00/00 


$ 
Money fields default to $0.00 


Data you enter in a field replaces its default 
value; if you do not enter data in a field, 
PERFORM 
stores the record with the default. 
If records are 
added through a form that does not include all the 
fields in a file, the omitted fields are filled with 
blanks or zeros, depending on the field type. 


With the DEFAULT attribute, you can change the 
default value for fields that are included on the 
form. 
Enter DEFAULT followed by an equal sign and 
the default value you want PERFORM to use. 
Default 
values for character and date fields must be speci- 
fied in quotation marks. 
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Below, the list3 field will default to "Santa 
Clara": 


list3 = city, required, default = "Santa Clara"; 


The TODAY keyword 


The today keyword causes PERFORM to use the 
current date as the default for a date field. 
If 
you add "defaul t=today" to the attributes list for a 
date field, 
PERFORM displays the current date in the 
format specified for the date field in the database 
schema: 


Data Type 


date 
edate 
ydate 


II.C.8. 
NOUPDATE 


Format 


mm/dd/yy 
dd/mm/yy 
yy/mm/dd 


You can protect fields that are not to be 
changed with the NOUPDATE attribute. 
For example: 


lamt = loan_amt, noupdate; 


II.C.9. 
NOENTRY 


The NOENTRY attribute is used instead of NOUP- 
DATE to prevent data entry in a field when adding 
new records rather than updating eXisting records. 


lamt = loan_amt, noentry; 


You can use the NOUPDATE and NOENTRY attributes 
together to create a field in which data is 
displayed but cannot be added or changed. 


For UNIX system users, additional flexibility 
in controlling access to the database is available 
using permissions. 
For a full explanation, see 
"User Access Privileges" in the DBBUILD chapter of 
this manual. 
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II.C.10. 
PICTURE 


Use the PICTURE attribute to specify a pattern 
for a field. 
Predictable patterns exist for certain 
types of data -- e.g., social security numbers and 
part numbers. 
PERFORM rejects input that does not 
conform to the pattern you specify with the PICTURE 
attribute. 
Use any combination of the following 
three symbols to represent the pattern you want: 


This symbol 


AH 
X 


Represents 


any letter 
any number 
any character 


PERFORM interprets any other character as a literal 
-- e.g., a decimal point represents a decimal point. 
If you attempt to enter an invalid character, 
the terminal beeps and PERFORM does not echo the 
character on the screen. 
However, the PICTURE at- 
tribute does permit you to leave trailing characters 
blank. 
In other words, the PICTURE attribute does 
not require you to fill in the entire field, as long 
as the characters entered conform to the PICTURE 
provided. 


For example, you might specify a field for so- 
cial security numbers like this: 


fl= socsec, picture = "HHH-HH-HHHH", 


defa ul t 
= 
" 
" ; 


PERFORM would accept any social security number 
as valid input. 
The default reminds operators of 
the required pattern. 


As another example, you might specify a field 
of part numbers like this: 


f1 = partno, picture = "AA###HH-AA(X)"; 


which would accept any of the following inputs: 


LF49367-BB(*) 
TG38524-AS(3) 
YG67489-ZZ(D) 
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II.C.11. 
QUERYCLEAR 


When you enter the Query command, 
PERFORM nor- 
mally clears all fields except joining fields. 
As- 
sign the QUERYCLEAR attribute when you want PERFORM 
to clear a join field, 
too. 
For example: 


proj 
= p-project 
*p_num, 
queryclear, 
reverse; 


causes PERFORM to clear the proj field whenever you 
select the Query command. 


An example of this comes from the bank data- 
base. 
Suppose that you desire information on a cus- 
tomer who holds a specific loan number. 
You can 
query for the record with the desired loan number. 
Using the customer number displayed, you then query 
for additional information about the customer. 
It 
would be desirable to leave the customer number on 
the screen following the first query so it need not 
be re-entered for the second query. 
(Under UNIX, 
the data may be manually cleared by typing CONTROL- 
C; under MS-DOS, type F10.) 


To clear data automatically from join fields, 
use the QUERYCLEAR attribute. 


bnum = cust num = borr_num, queryclear; 


II.C.12. 
REVERSE 


The REVERSE attribute can be used to indicate 
that a field should be displayed in reverse video, 
if the terminal being used supports this feature. 
For example: 


lnum = loan_num, reverse; 


II.C.13. 
RIGHT 


You can use the RIGHT attribute to right- 
justify the value in the field. 
The default is to 
have the contents of the field left-justified in the 
display field. 


lamt 
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loan_amt, right; 
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II.C.14. 
ZEROFILL 


Assign the ZEROFILL attribute to the fields 
that you want to be right-justified and padded with 
leading zeros. 
This attribute is most useful with 
numeric fields. 
If the number in the field is 
shorter than the field itself, PERFORM right- 
justifies it and replaces the leading blanks with 
zeros. 
For example: 


lamt = loan_amt, zerofill; 


The ZEROFILL attribute only 
wor~-for display 
fields that correspond to integer, long, serial, 
character, or money database fields. 


II.C.15. 
UPSHIFT 


Assign the UPSHIFT attribute to a character 
field when you want PERFORM to convert lowercase 
letters to uppercase. 
PERFORM stores and displays 
data entered in an UPSHIFT field in uppercase. 
For 
example: 
. 


ltype = loan_type, upshift; 


Because upper- and lowercase letters have dif- 
ferent ASCII values, storing all character strings 
in one or the other format can simplify sorting and 
querying a database. 


II.C.16. 
DOWNSHIFT 


The DOWNSHIFT attribute works like UPSHIFT, ex- 
cept that PERFORM converts from uppercase to lower- 
case. 
If neither UPSHIFT nor DOWNSHIFT is used, 
data appears as entered, in upper-, lower-, or mixed 
case. 


II.C.17. 
FORMAT 


If a display field refers to a float or double 
field, the FORMAT attribute can be used to indicate 
how many decimal places are to be printed when the 
field's values are displayed. 
The pound sign (#) 
character is used to format the display. 
An example 
is shown below. 


qty = quantity, format = "U#.##"; 
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The qty field in the database displays quantity 
values in a field six characters wide with the 
decimal point positioned so that there are two 
places to the right of the decimal point. 


When using format strings, the decimal point 
may be positioned anywhere, and the display field 
can be any length. 
The number is right-justified 
and blank-padded on the left. 
Zeros will appear to 
the right of the decimal if no number is entered. 


However, the format string should be the same 
size as the display field. 
Otherwise, a FORMBUILD 
warning will result. 


II.C.18. 
Attributes with Joined Fields 


A display field can represent two (or more) 
fields joined from separate files and can have vari- 
ous attributes for the fields it represents. 


The placement of attributes determines when 
they take effect. 
If you want an attribute to apply 
at all times, place it after the last field name. 
For example: 


tag = field1 = field2, verify; 


joins tield1 to tield2, and PERFORM requires opera- 
tors to enter data twice for verification. 


You can also specify attributes that apply only 
when a certain file the current file (see V. B "The 
FILE Command"). 
For example: 


tag 
field1, verify; 
field2; 


This statement also joins field1 to field2. 


When the tleld1 file is current, 
PERFORM requires 
operators to enter data twice, whereas when the 
fleld2 file is active, no verification occurs. - 


The FORMAT and REVERSE attributes always take 
effect, regardless of their placement. 
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II.D. 
Preparing the Form Specification File 


After you use a text editor to create a form 
specification file, you must use FORMBUILD to com- 
pile, or translate, it into a form for use by PER- 
FORM. 


To compile the form specification file rea11, 
use the following command: 


~ formbuild real1 


(The examples used in this chapter are named 
rea11, real2, real3, and real4.) 


A successful compilation yields a new operating 
system file with the extension .fr. added to the end 
of the file name. 
In this case, the new file would 
be named real1.frm. 
If there are typing mistakes in 
the file or the file is not structured correctly, an 
error-listing file named real1.err is created. 
You 
can review this file and correct the errors in the 
original specification file, which should then be 
recompiled. 
If you use the "verbose" option, 
FORMBUILD 
gives you warnings in an .err file if there are 
display fields in the form which are not the same 
size as the field in the database. 
To use the ver- 
bose option, use the -v flag. 
Under MS-DOS, you 
must use a lowercase v. 


A> formbuild -v real1 


The -v option is particularly useful when you 
have edited the form file extensively and would like 
FORMBUILD to conduct a final check. 
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III. 
Browsing Through Existing Data: 
The QUERY, 
NEXT and PREVIOUS Commands 


Once a form has been created by compiling a 
form specification file, 
PERFORM can be used to be- 
gin viewing data in the database. 
PERFORM can be 
selected on the INFORMIX Master Menu or run using 
the command below. 


% perform rea11 


If no form is specified on the command line 
when PERFORM is run, the user will be prompted for 
the name of the form. 
PERFORM will print the names 
of all the forms in the current directory and ask 
the user which one is desired. 
If only one form is 
available, it will be selected by default. 


Figure 5 shows a PERFORM screen • 
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Query Next Previous Add Update Remove File Screen Current Master Detail 
Output Bye 
•• ,: listings 1'l1a" 


Real Estate Listings tor Single Family Dwellings 
in Santa Clara County, Cali1'ornia 


agent name [ 


listing number 
[0 
J 


street address 
city 


footage 
(0 
1 


11 st ing note 


bedrooms 
[0 
1 


aaking price 
(SO.OO 
1 


baths 
[0 
1 
10ts1ze 
(0.0 


sale price 


[SO.OO 


corner 
schools 
( 1 
( 1 


Figure 5. 
PERFORM screen for the listings file. 
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The commands shown at the top of the screen can 
be executed by typing the first character of the 
command, in either upper- or lowercase. 
For exam- 
ple, typing a calls the 
ADD command, u the UPDATE 
command, and so forth. 
Pressing any of these keys 
causes the command to execute until you press the 
ESCAPE key to complete the command or the DELETE key 
to abort it. 
Type b (for BYE) to end the PERFORM 
session. 


The QUERY command is used for finding certain 
records in the database. 
Type q, and then fill in 
one of the fields with a search value. 


In Figure 6, the listing number field has been 
filled in with a 3. 
When you-press the ESCAPE key, 
all of the records with a listing number of 3 will 
be located and put in the "Current List" for the 
listings file. 


The Current List can be examined with the 
NEXT 
and PREVIOUS commands. 
If another query is done, a 
new Current List is created. 


Each file has its own Current List. 
If the 
current file is changed using the FILE command, the 
Current List for the file is maintained, in case the 
file is re-selected with the FILE command later. 
Since there is only one file involved in this exam- 
ple, there is only one Current List. 
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QUERY: 
ESC executes. 
DEL aborts. 
CTRL C clears all. 


u 
help for help. 
1: listings file" 


Real Estate Listings for Single Family Dwellings 
in Santa Clara County. California 


agent name [ 


listing number 
[3 
1 
atreet address 
city 


footage 
1 


listing note 


Searching••• 


bedrooms 
[ 
J 


asking price 
[ 
J 


baths 
[ 
1 
lotsize 


sale price 


corner 
schools 
[ J 
[ 
J 


Figure 6. The QUERY command, searching for records 
with listing number equal to 3. 
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Query Nest Previou. Add Dp4ate 
ae~ve rile Screen Current 
Mas~er Cetail • 


OutllUt Bye 
•• 1, l.I..tin9. file·· 


"al Eatate Li.tin98 for Single Paaily Dwellings 
in Santa Clara County, CAlifornia 


agent n... IO'Brian, Sean 


l.I.ning nu8bar 


13 
) 
street address 


(543 W. Bill n. 
city 
(Madison 


footage 
11500 
) 


badroo•• 
[2 
) 
batb. 
12 
) 
lotshe 


11.5 
cor"er 


lI') 
school. 
[tl 
uking pric. 
1f150000.00 


li8ting note 
I'" carpet., drape•• 


1 raoord(s' found 


sal. price 
I~.OO 


Figure 7. The QUERY command completed. 
One record 


with listing number equal to 3 is found, displayed, 
and put in the Current List. 
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In the example shown in Figure 6, only one 
record was found. 
This one record, shown in Figure 
7, becomes the Current List. 


In addition to searching for equal values, you 
can search on the basis of inequality. 
To find 
records with listing numbers 3 or higher, use the >= 
symbol, as shown in Figure 8. 
Figure 9 shows the 
results of the search. 
The 14 records found replace 
the old Current List, which contained only one 
record. 


QUERY: 
ESC executes. DEL aborts. 
CTRL C cl.ars all. 
help 
Cor help • 
•• 1: listings Cl1e·· 


Real Estate Listings 
Cor Slngle Famlly oVell1ngs 


in Santa Clara County, Cal1!ornia 


1isting number 


[>-3 
J 
street address 
city 


11sting note 


Searching••• 


bedrooms 
[ 
J 


asking price 
[ 
J 


baths 
[ 
J 
lotsize 


sale price 


corner 
schools 
[ J 
[ 
J 


Figure 8. A QUERY searching for records with listing 
numbers greater than or equal to 3. 
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Query Next Previous Add Update Remove File Screen Current Master Detail 
Output Bye 
•• 1: listings file" 


Real Estate Listings for Single Family Dwellings 
in Santa Clara County. California 


agent name (O'Brian, Sean 


listing number 


(3 
] 
street address 
[543 W. Hill St. 
city 
(Madiaon 


footage 
[1500 
1 
bedrooms 
(2 
1 
baths 
(2 
1 
lotsize 
(1.5 
corner 
(N] 
schoc 
(Y 


asking price 
[S150000.00 


listing note 
(New carpets. drapes. 


6 record(s) found 


sale price 
(SO.OO 


Figure 9. The result of the query. 
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The 8 records in the new Current List can be 
examined by stepping through them with the NEXT and 
PREVIOUS commands. 
NEXT steps forward through the 
list and PREVIOUS steps backward. 


The NEXT and PREVIOUS commands may be repeated 
by typing a number before the command. 
For example, 
if you type 7n, the record in the Current List 7 
records forward from the record on the screen is 
displayed. 


Queries can involve more than one field. 
Each 
field can contain either a search value or a rela- 
tional operator followed by a search value. 
No 
records are found unless they satisfy all of the 
criteria in all of the fields for which search 
values have been entered. 


The RETURN key causes the cursor to move from 
one field to the next on the screen during the 
QUERY, 
ADD, or UPDATE commands. 
The order of the 
fields in the attributes list determines the order 
in which the cursor travels from field to field. 


The relational operators you can use are: 


>= 
<= 
<> 
< 
> 
If a field is left blank during a query, that 
field is ignored in the search. 
In order to search 
specifically for a character field that is blank, 
the equal 
(=) sign must be used. 
This character 
tells PERFORM to take the characters that follow it 
literally. 
Thus, putting = alone in a field will 
cause PERFORM to search for a field in which no data 
has been entered. 


The asterisk (*) character has a special effect 
when performing searches on character fields. 
For 
example, filling in the listing note field with 
*pool* would find all records with the word pool in 
that field, whether the· word "pool" is in the por- 
tion of the record displayed on the screen or not. 
The expression pool* would only look for fields be- 
ginning with the word "pool." To search for a field 
containing an asterisk, enter =*. 


You can also specify a range of values as the 
search criterion for a field. 
This is done by plac- 
ing the low and high limits for the range into the 
field, separated by a colon (:) (e.g., 1001:1050). 
The range is inclusive. 
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You can search for the first record in the file 
based on the sorted ordering of one of the file's 
indexed fields. 
This can be done by entering two 
less-than symbols 
(<<) in the field to mean "find 
the first record" or two greater than symbols (») 
to mean "find the last record." 
This can only be 
done on indexed fields. 


If a search criterion specification is longer 
than the display field, 
PERFORM automatically 
creates a temporary work area at the bottom of the 
screen. 
This area disappears when you press RETURN 
to move to the next field or when the search is ini- 
tiated by pressing the ESCAPE key. 


Characters other than the RETURN key may be 
used to move the cursor around on the screen during 
the QUERY, 
ADD, and UPDATE commands. 
The BACKSPACE 
key, the LEFT ARROW key, and CONTROL-H move the cur- 
sor back one character within a field. 
The RIGHT 
ARROW and CONTROL-L move the cursor to the right one 
character (without overstriking the character with a 
blank). 
The 
DOWN ARROW and CONTROL-J move the cur- 
sor to the beginning of the next field, 
and the UP 
ARROW or CONTROL-K move the cursor to the beginning 
of the previous field. 
. 


Other keys may also be used to perform special 
functions. 
For the ADD or UPDATE commands, a 
CONTROL-W may be typed to get a summary of special 
CONTROL characters. 
The help screen that is printed 
when a CONTROL-W is typed is shown in Figure 10. 
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FIELD EDITING CONTROL KEYS: 
CTRL X 
Deletes a character 


CTRL A 
Toggles in and out of character insertion mode 
CTRL D 
Clears to the end of the field 
left 
Backspace 
right 
Forward space 
up 
Traverse backwards through the fields 
CTRL F 
'Fast-forward' through the fields 
CTRL B 
'Fast-reverse' through the fields 
CTRL C 
Clears all fields 
(Query mode only) 
CTRL P 
Brings in most recent field value of the record 


CTRL W 
Display help message 
CR 
Next field 
CTRL I 
Next field 


down 
Next field 
ESC 
Entry Complete 
DEL 
Abort Command 


Less than or equal 
Greater than or equal 
Not equal 
fields, without other comparisons) 
as last value) 
»« 


QUERY 
<> 


COMPARISON SYMBOLS: 
Less than 
<.. 
Greater than 
>.. 
Equal 
<> 
Last value (only for indexed 
First value (same conditions 
Range 
(inclusive) 


The colon for range comparison is typed between the 


desired range values. 
All other symbols are typed 
in front of the field value 


An asterisk (*) is used for wild card comparison of 


character fields 


A blank field means don't care 


To match for a blank character field, use the 
equal!ty symbo 1 


Figure 10. The PERFORM help screen. 
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IV. 
Changing the Contents of a Database 


IV.A. 
UPDATE 


The UPDATE command allows you to change the 
contents of the currently displayed record. 
It is 
initiated by typing u to the command prompt and then 
using RETURN or other cursor-positioning keys to 
move around on the screen and change the displayed 
data. 
When the ESCAPE key is typed, the record is 
updated in the database itself. 


If you try to make a change that violates any 
characteristics specified in the ATTRIBUTES section 
of a form specification file, 
such as entering a 
number outside a specified range, 
PERFORM alerts you 
on a field-by-field basis. 
PERFORM does not allow 


the cursor to travel outside the field until there 
is a valid entry in it. 


However, other update errors are not detected 
until you press the ESCAPE key. 
For example, check- 
ing for a duplicate entry in a field which has been 
indexed as NODUPS with DBSTATUS occurs after the ES- 
CAPE key is pressed. 


The REQUIRED attribute only affects the addi- 
tion of records to the database. 
You can delete 
data from a field even if it is marked with the RE- 
QUIRED attribute. 


IV.B. 
ADD 


When you press a, the screen displays blank 
fields or default values and is ready for adding new 
data. 
Fill the fields with the desired data and 
then press the ESCAPE key to add the record to the 
database. 
When the form includes fields from more 
than one file, press f to move from one file to the 
next. 
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IV.C. 
Im(OVE 


When you press r, 
PERFORM asks you to verify 
that the record is to be deleted. 
Press Y or y and 
RETURN. 
The record will be deleted, and a message 
to that effect will be printed at the bottom of the 
screen. 


IV.D. 
OUTPUT 


Press 
0 for the OUTPUT command to send the 
results of a PERFORM query to an operating system 
file. 
PERFORM prompts for the name of the file. 
This should be an operating system file name or a 
complete path name. 
PERFORM then asks if the file 
is to be created or if the data should be appended 
to an existing file. 


You can choose to send either the current 
screen or all records in the Current List to the 
spec ified file. 


You can also use the OUTPUT command to send 
output directly to a printer. 
Under UNIX, printers 
are configured as device files, 
and sending output 
to Idev/lp causes it to be printed. 


Do not use the UNIX device file name on multi- 
user systems. 
This avoids the situation where 
several print jobs are be sent to the printer at the 
same time. 
In such cases, the output should be sent 
to a file, and spooled (or lined up) for output, 
typically using a program called "lpr". 


Under MS-DOS, you can send output directly to a 
printer by entering Iptl as the output file. 
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v. 
Advanced Features 


V.A. 
The SCREEN ColDllland 


A form may take up more than one screen. 
For 
example, the form specification file in Figure 11 
spreads the real estate form across two screens. 
Each set of curly brackets {} defines one screen. 
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database realty 
acreen 
{ 


Real Estste Listings for Single Family Dwellings 
in Santa Clara County, California 


sgent name [list1 


listing number 
(list2 ) 
street sddress 
[list3 
[ l1st4 city 


footage 
[UstS 
] 


screen 
I 


bedrooms 
rUst6 
J 
baths 
[ l1st7] 
lotsize 
[ listS 
corner 
.schools 
[xl 
[y) 


asking pr 1ce 
[list9 
) 


listing note 
[list11 
} 
end 


attributes 


sale pr1ce 
[ list10 


list1 • broker; 
list2 • listing number, include. (1 to 30000), required; 
list3 • address7 required; 
list4 
city, required, default. "Santa Clera"; 
listS. footage, include. 
(SOO to 4000), 


comments. "Enter a number from SOO to 4000."; 
list6 • bedrooms, 1nclude • (1 to 1S), 
comments. "Enter a number from 1 to 15."; 
list7 • baths; 
listS. lot size, 


comments. "Enter acres or portions; 
.S 1s.half en scre."; 
x 
• corner lot, 1nclude • (Y,N,y,n), upshift; 
y 
achools, 1nclude • (Y,N,y,n), upshift; 
list9 • asking-price, required; 
list10 • sales pr1ce; 
list11 
listing_note1[1,4S]; 


end 


Figure 11. The rea12 form. 
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PERFORM ini tially displays the first "screen 
page" of this file. 
To display the next page, press 
s to call the SCREEN command. 
If there are several 
screens in the form, the SCREEN command cycles 
through from one to the next, and back around to the 
first when you are on the last page. 
The only limit 
to the number of screens is the available computer 
memory. 


Query .ezt 
'revi~u. Add Update Raaove Pile Screen ...t.r Detail lye 
""li_ting_ file"" 


..ai E_tate Li_ting. for Slngle ,..11y Dweillng. 


In Santa Clara County, Callfornla 


.. 


<io. 
CP 


agent n..e ( 


U_Ullg Il&.oer 


(0 
I 
.tr..t addte•• 
dty 


footag_ 


(0 
I 


bedtOOM 
[0 
I 
bath. 
lot.ire 


(0 
I 
10.0 
cornet 
.choola 
( ) 
[ 1 


Figure 12. First screen of rea12 multi-screen form. 
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Qu.ry ••xt ,r.vloua Add Updat. ..-0.. 'il. SCr••n CUrr.nt Keat.r Datail 
OUtput Iy. 
•• 1. liatlnga fl1a-- 


l1atlng not. 


nUng pdc. 
lfO.OO 
I 
aal. pdc. 
IfO.OO 


Figure 13. Second screen of rea12 multi-screen form 
after the SCREEN command. 
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V.B. 
The FILE Command 


If your form includes fields from two or more 
files, brackets surround the fields of the first 
file represented in the ATTRIBUTES portion of the 
form specification file. 
This is the current file, 
and all queries, updates, or additions pertain to 
this file. 
When the SCREEN-command moves to the 
next page of a multi-page form, any fields from the 
current file will be bracketed on the new screen. 


The FILE command is used to switch among the 
files in a form. 
Just as the SCREEN command rotates 
through the screens in a form, 
the FILE command ro- 
tates through the files. 
When you press the F key, 
the brackets disappear from the fields of the 
current file and reappear around the fields of the 
next. 


The form specification file in Figure 14 has 
fields from both the listings and the agents files 
of the realty database. 
The form defined here is 
called rea13. 


Figure 15 shows the rea13 screen that PERFORM 
first displays. 
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database realty 
screen 
{ 


Real Estate Listings for Single Family Dwellings 
1n Santa Clara County, California 


agent name 
[list1 


listing number 
[list2 ] 


agent phone 
[new1 
] 


street address 
[ list3 


agent address 
[new2 


city 
[ list4 


footage 
[list5 
] 
bedrooms 
[list6 ] 
baths 
[ list7] 
lots1ze 
[ listS 
corner 
[x] 
school s 
[y] 


asking price 
[list9 
] 


listing note 
[list11 
} 
end 


attributes 


list1 • agent_name • broker; 
new1 • agent-phone; 
new2 • agent_address; 


sale price 
[ list10 


list2 • listing_number, include. {1 to 30000), required; 
list3 • addreas, required; 
list4 • city, required, default. "Santa Clara"; 
list5 • footage, include. {SOO to 4000), 


comments. "Enter a number from SOO to 4000."; 
list6 • bedrooms, include. {1 to 15), 
comments. "Enter a number trom 1 to 15."; 
list7 • baths; 
listS. lot size, 


comments. "Enter acres or portions; .5 1s half an acre."; 
x 
• corner lot, include. (Y,N,y,n), upshift; 
y 
schools, include. (Y,N,y,n), upshift; 
list9 • asking price, required; 
list10 • sales-price; 
list11 
listing_note1 [1,45]; 


end 


Figure 14. Form specification file for the real3 
form. 
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Query aeat 'reviou. Add 
a~ate Jaaove rile Scr.en Current Ka.t.r Detail 
OUtput lye 
•• 11 a,ent. fU.·· 


..&1 Eatat. L1.t1n,. for Sin,l. r..11y Dwell1n,. 
1ft Suta Clara COWlty, california 


..Ung price 
$0.00 


U.Un, noe. 


batlla 
o 
loUin 
0.0 


aal. price 
SO.OO 


lIity 


lIoner 
.cboOla 


Figure 15. Multiple file form (real3) with agents 
file selected. 
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Use the FILE command to cycle through the files 
on a form, just as the SCREEN command cycles through 
the screens of a form. 
When using forms composed of 
multiple screens, the FILE command also causes the 
screen with the largest number of fields from the 
next file to be displayed. 


If there are fields from several files on the 
same screen, each time the FILE command is typed the 
brackets change to another file's fields. 


Figure 16 shows the effect of typing the FILE 
command. to switch to the listings file from the 
agents file. 


Query Haat Previooa Add Updata Ramove Pile Scraan Current Kaater Detnil 
OUtput Bya 
•• 1. liatinga fila-- 


aeal Batate Liatinga for Singla 'aaily Dwellinga 
in lanta Clara County, CAlifornia 


liating numar 
[0 
I 


a,ent pbona 


.treat addr••a 


a,ent addre•• 


city 


fClOtage 
[0 
I 


bedrco•• 
[0 
I 


batb. 
[0 
J 
lotaha 


[0.0 
corner 
[ I 
.cbool. 
[ I 


a.king price 
[$0.00 


listing note 


••1. price 
[$0.00 


Figure 16. Multiple file form with listings file 
selected with the FILE command. 
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The FILE and SCREEN commands can be preceded 
with a number which indicates the absolute number of 
the file or screen to be accessed. 
Thus, the com- 
mand 28 always causes the second screen in the form 
to be displayed and 
2~ always moves you to file 
number two in the form. 
The file number is shown 
before the file name in the PERFORM screen header. 
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v. C 
The CURRENT Command 


The CURRENT command rereads and redisplays the 
current record in the Current List of the active 
file. 
It is useful in two situations: 


e 
Multi-User Systems: If several people use a da- 
tabase simultaneously, another user may modify 
a record while it appears on your screen. 
The 
CURRENT command rereads the record from the da- 
tabase and displays the most up-to-date.infor- 
mation. 


e 
Multiple-File Forms: PERFORM maintains a 
separate Current List for each file included on 
a screen form. 
When a form includes a join 
field, 
browsin~ through the records in the ac- 
tive file often causes PERFORM to display dif- 
ferent data from the other files, with the 
results that you may occasionally nlose your 
place n in one or more of the Current Lists. 


The CURRENT command returns you to your origi- 
nal position in the Current List for the active 
file. 
. 


V.D. 
Joins and Multiple-File Forms 


In the multiple-file forms discussed so far, no 
association between the files was stated in the form 
specification file. 
PERFORM allows you to specify 
associations between files in a multiple-file form 
with joins and with the MASTER and DETAIL commands. 


Through the use of multiple-screen forms, 
multiple-file forms. join fields, and MASTER-DETAIL 
relationships, 
PERFORM can be used for powerful re- 
lational queries. 


The schema for the realty qatabase is shown 
again In Figure 17 for reference. 
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{PRINT SCHEMA} 


database realty 


fUe listings 


field listing_number 
type integer 
field address 
type character 
length 20 


!ield city 
type character 
length 20 
field footage 
type integer 
field bedrooms 
type integer 


field baths 
type integer 


field lot size 
type double 
field corner lot 
type character 
length 1 


!ield schools 
type character 
length 1 
field asking price 
type money 
field sales price 
type money 
field broker 
type character 
length 15 
index dups 
field listing_note1 
type character 
length 45 


file agents 


field agent_number 
type integer 
field agent_name 
type character 
length 15 
index 
field agent_address 
type character 
length 20 
field agent_city 
type character 
length 10 
field agent_zip_code 
type long 
field agent_phone 
type character 
length 8 
field agent_salary 
type money 


Figure 17. Schema for the realty database. 


V.D.1. 
Joins 


The agents file contains a field with the 
agent's name, called agent name, as well as other 
information about the agent. 
The listings file con- 
tains the name of the listing agent in the broker 
field. 
These fields both contain the names of real 
estate agents working out of the. same office. 


The fields agent name and broker can act as 
join fields, since both contain the name of an 
agent. 
Join fields used on PERFORM forms must both 
be indexed. 


Since an agent may have several homes listed 


....-.." 
.·t 
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under his or her name, there may be many records in 
the listings file with the same agent name. 
The 
agents file, however, will contain only one record 
per agent. 
In the real3 form specification file, 
the broker and agent name fields are equated to the 
same display field label. 
This means that the agent 
name is displayed on the screen, no matter which 
file is active. 


This arrangement can be exploited to answer a 
cross-file query, for example, "find the homes with 
3 bedrooms and show the phone number of the listing 
agent." In this case, the number of bedrooms is in 
the listings file, and the phone number of the agent 
is in the agents file. 


The query is performed as follows. 
First the 
listings file is queried to find all of the homes 
with 3 bedrooms. 
When a listings record is ' 


displayed on the screen, the associated agents in- 
formation is also displayed. 


If the current file is changed using the FILE 
command, and then a NEXT is performed, a message 
will indicate that there are no more records in the 
Current List for the current file. 
It may be desirable to query the agents file to 
locate an agent on the screen, and then query the 
listings file to find all of the homes that are 
listed by that agent. 
In the last example, if the 
current file is the agents file and a query is done, 
the first listings record for the agent is also 
displayed on the screen. 


The fields of a file joined with the current 
file will be filled in with the first associated 
record found. 
An associated record does not become 
the Current List. 
The Current List for a file can 
only be changed with the QUERY, 
MASTER, or DETAIL 
commands. 


To find the rest of the listings records for 
homes that are listed by the agent on the screen, 
use the QUERY command. 
When the QUERY command is 
executed, the fields of the current file are cleared 
so that· the query may be entered. 
However, the con- 
tents of the join field for the current file are not 
cleared. 
Pressing the ESCAPE key initiates the 
search. 
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V.0.2. 
The MASTER and DETAIL Commands 


You can handle this type of cross-file query 


mo~e easily with the MASTER-DETAIL commands. 
An IN- 
STRUCTIONS section in a form specification file al- 
lows you to use the MASTER-DETAIL commands. 
The 
form specification file in Figure 18 includes an IN- 
STRUCTIONS section (after the ATTRIBUTES section). 


The instruction "agents master of listings" 
means that listings is a "detail" file of agents. 
With this instruction included, the DETAIL command 
automatically switches to the listings file and per- 
forms the query. 


Since this form only has two files on the 
screen, the FILE command would also switch you back 
to agents. 
However, the MASTER and DETAIL commands 
are necessary when there are several files included 
in a form. 


To summarize, the DETAIL command switches to 
the file which has been designated as the detail 
file of the current file and automatically performs 
a search on that file, using the value in the join 
field. 
The MASTER command can be used to switch 
back to the file which is the master of the current 
file. 


You can do a great deal of cross-file searching 
with simple keystrokes if master-detail relation- 
ships are used. 
For example, the agents file could 
be queried to find a selected group of records, 
which would be put in the agents Current List. 
These records could be searched with the NEXT and 
PREVIOUS commands. 
When an agent of interest is 
found, pressing d for DETAIL would switch files to 
listings and automatically find all of the 
associated listings records. 


These records could be stepped through using 
the NEXT command. 
Then the agents file could be 
re-selected with a MASTER keystroke, and the next 
agent on the old agents list could be viewed. 
Only 
single keystrokes are needed to switch between the 


~iles and to trigger master-detail searches. 
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database realty 
screen 
{ 


Real Eatate Liatings tor Single Family Dvellinga 
in Santa Clara County, Calitornia 


agent nama 
[l1st1 


listing number 
[l1at2 J 


agent phone 
J--- 
[nev1 
1 


street addreaa 
[l1st3 


agant address 
[nev2 


city 
[ l1st4 


tootage 
[l1at, 
J 
bedrooma 
(l1st6 J 
batha 
[ l1st7J 
lotaize 
[ listS 
corner 
schoola 
(xl 
[yJ 


eaking price 
(l1st9 
J 
listing note 
(list11 
Iend 


ettributes 


Ale price 
[l1at10 


list1 • agent_ne... broker; 
nev1 • egent phone; 
nev2 • agent-address; 
liat2 • liatIng_number, include' (1 to 30000), required; 
liat3 • addreaa, required; 
liat4 • city, required, detault • "Senta Clara"; 
liat5 • tootage, incl ude " (aoo to 4000), 
liat6 • bedrooaa, include. (1 to 1'), 
coa..nts • "Entar a number trom , to 15."; 
l1at7 • baths; 
liatS • lot size, 
com"nta • "Enter acrea or portiona; ., is halt an acre."; 


x 
• corner lot, include" (Y,N,y,n). upahitt; 
y 
• achools,. include. (Y,N,y,n), upshtrt; 
liat9 • eaking-price, required; 
liat10 • Ales-price; 
list1' • liating_note'(1.4,J; 


inatructiona 


agenta eaater ot liatinga; 
end 


Figure 18. Form specification fi1e tor rea14. 
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The order of the files in the master-detail 
specification does make a difference. 
In the form 
specification file for real4, listings could have 
been master of agents instead of" the other way 
around. 
However, since there are only two files in 
the form, and since there is only one record for 
each agent, making listings the master of agents 
provides no additional features. 


When the listings file is current and a record 
is displayed, the first associated agents record is 
also 
displa~4. 
It is the only associated agents 


record, since there is only one record for each 
agent. 
In this case, the DETAIL command would per- 
form exactly the same function as the FILE command. 
If another file was included in the form, it 
might be helpful to have listings the master of 
agents, since the MASTER and DETAIL commands could 
be used to switch back and forth between the two 
files easily, whereas the FILE command would cycle 
through all of the files in the form. 


There may be as many MASTER-DETAIL relation- 
ships between files in the form as makes sense. 
A 
file can be the MASTER and DETAIL of the same file. 
In other words, listings could be the master of 
agents, and agents could also be the master of 
listings. 


A single file can be master of more than one 
detail file. 
The desired master-detail relation- 
ships are all listed separately. 
Each file is as- 
signed a number on the PERFORM screen. 
It is possi- 
ble to move to a particular detail file by putting 
the appropriate number before d. 
Thus, typing 4d 
after a query on the master file will produce the 


rel~ted records from file 4 in the form. 
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V.E. 
Composite Joins 


You can join composite fields on PERFORM forms •• 


You might want to use composite fields if, for exam- 
ple, neither last name nor first name is a unique 
identifier, but the combination provides a composite 
indicator which is unique. 


The composite join is indicated in the INSTRUC- 
TIONS portion of the form specification file. 
When 
you specify a composite join, you must include all 
the component fields as display fields on the form. 
Also, all joins among components must be 
lis~d in 
the ATTRIBUTES section of the form specification 
file. 
Joined component fields must match in data 
type and length, as always, but they need not be in- 
dexed. 
An example is shown in Figure 19. 


database newbank 
screen 
{ 


LOAN INFORMATION WITH COMPOSITE 
J~IN 


Loan Number [num 
] 
Borrower Number [borr 
] 
Borrower Name (last 
} 
end 
J [first 


attributes 
num 
= loan num; 
borr 
= borr-num = cust num, 
requi~ed; 
last 
= borr-lname = cust lname, required; 
first 
= borr:fname 
= cust:fname, required; 


instructions 
composite join 
borr_id = cust_id; 


end 


Figure 19. Form specification file with a composite 
join. 


This example assumes that the fields borr id 
and cust id have been defined as composite fierds in 
the dataoase schema. 
Each is composed of three 
fields, representing first name, last name, and 
number. 
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Notice that: 


• 
The composite join is indicated in the INSTRUC- 
TIONS section of the form specification file. 


• 
The three component fields of the composite 
fields are included as display fields in the 
form. 


• 
The join among each pair of component fields is 
listed. 


V.F. 
Field Delimiters 


By default, fields on PERFORM forms are en- 
closed in square brackets ([J). 
You can specify al- 
ternate field delimiters in the INSTRUCTIONS section 
of the PERFORM screen. 
The delimiter command is 
followed by two characters enclosed in double quotes 
as shown below. 


instructions 
delimiters "<>"; 


Blanks may be used as delimiters in the IN- 
STRUCTIONS section; however, in screens composed of 
more than one file, 
some visible delimiters should 
be used to allow the user to identify fields in the 
current file. 
Fields should be 
enclo~ed in square 
brackets ([J) in the SCREEN section. 
FORMBUILD uses 
these square brackets. 
If you specify DELIMITERS in 
the INSTRUCTIONS section, 
PERFORM replaces the 
square brackets 
o~ the screen with the DELIMITERS 
you specify. 


(If your terminal does not use square brackets, 
for ASCII codes 5B and 50 hex, 
FORMBUILD will use 
the other characters represented by these codes. 
If 
you want to use a different character in the SCREEN 
section, precede the character with a backslash in 
the SCREEN section. 
This character will not appear 
on the screen when you run PERFORM; it is only for 
FORMBUILD's use in compiling your form.) 
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V.G. 
Special Function Keys under UNIX 


PERFORM uses the UNIX Termcap facility. 
Termcap information is stored in the directory 
letcltermcap and describes the cursor control func- 
tions of many popular computer terminals. 
PERFORM 
reads this file and looks for the name of the termi- 
nal currently being used. 
(The TERM shell variable 
should be set to the appropriate Termcap terminal 
I.D. before PERFORM or any other INFORMIX screen- 
oriented software is run.) 


There are other uses for the letc/termcap file. 
Those users who are familiar with letc/termcap may 
know that there are certain key· transformations 
which may be indicated in the letcltermcap file for 
using function keys. 
Most of the special function 
keys send a special character, or a short sequence 
of characters. 
The letc/ter.cap entry can be modi- 
fied so that these sequences are translated into 
characters expected by PERFORM. 


For example, suppose a specific terminal had a 
function key that either was labeled, or could be 
labeled, EXECUTE. 
This might seem like a more obvi- 
ous name for a key that is used to initiate a com- 
mand. 
Using the key translation technique of the 
Termcap system, PERFORM can recognize such renaming 
of keys. 
It is up to the user to determine whether 
or not this feature can be utilized. 
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VI. 
Examples 


VI.A. 
Order Entry: 
A Tvo-SCreen Form with 
Four Files 


The schema in Figure 20 describes a 4-file da- 
tabase which might be used for an order entry type 
of application. 
The four files store data about an 
order, the customer placing the order, the items on 
the order, and descriptions of those item parts in 
an inventory. 


The form specification file in Figure 21 con- 
tains fields from four files, in two screens. 
The 
"page" designation is interchangeable with "screen" 
in the form. 
Notice that the invoice number is on 
both screens of the form. 
Also notice the three 
joins which are specified. 
Using this form, orders 
can be viewed, entered and updated. 


Since the information is joined with three join 
fields, all with a dominant field specified, new in- 
formation is kept consistent among the files in- 
volved. 
Also, gathering all of the data pertaining 
to a customer or order is easy. 
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{ORDERS SCHEMA} 


database orders 


f'ile order 


f'ield orderno 
type character 
length 20 
index 
field odate 
type date 
field shipdate 
type date . 
f'ield ocustno 
type integer 
index dups 
field agent 
type character 
length 20 
field instruct 
type character 
length 256 
field backlog 
type character 
length 1 
field ponum 
type character 
length 15 
end 


database orders 
file items 


f'1eld iorderno 
type character 
length 20 
index 


f'ield ipartno 
type character 
length 20 
index dups 
field orderqty 
type integer 


f'ie ld totalp 
type money 
end 


database orders 


f'ile customer 


field custno 
type integer 
index 
field custname 
type character 
length 20 
field custaddr 
type character 
length 20 
field custcity 
type character 
length 20 
field custstate 
type character 
length 2 
field custzip 
type long 
field custphone 
type character 
length 15 
end 


database orders 


file parts 


field partno 
type character 
length 20 
index 
field desc 
type character 
length 20 
field price 
type money 
f'ield unitqty 
type integer 
end 


Figure 20. The orders schema. 
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4.tab... 0..4.... 


acr••n 


-----------------------------------------------.----------------------- 
Comp.ny n••• : 
1£6 
]] 
Ad4.....: 
£7 


C1ty: 
£8 
St.t.: [£9] 
Z1p:[h1 
Phon. Numb... : 
h2 
] 
Coap.ny nu.ba.. : 
£5 
] 


Inv01c. nueba.. : 
[£1 


S.l•• Pa...on: 
[£3 


Pu..cha.. 0..4... ,: 
Spec1.1 In.t..uct10n.: 


acr••n 


{ 
Invo1c. numba.. : {£1 


[h3! 


11 
12 
13 
[14 


Dat. 0..4....4: 
(f2 


O.t. Sh1ppe4: 
[f4 


B.Cklog/Full: [x] 


""""""""""""""""""""""""""" """"""""" 
p...t nueb... 
descr1ption 
pr1c. 
qu.ntitf 
total pr1ce 
lp1 
] 
[ p2 
] "[p3 
] 
lp4 
J 
[p5 
] 
"""""""""""""""""""""""""""""""""""" 
I 


.n4 


Figure 21. Form specification file. 
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attt'ibutes 


£6 • custname, t'equit'ed, downshift; 
f7 • custaddt', noupdate; 
£8 • custcity, include. (" ", sf); 
£9 • custstate, upshift; 
h1 • custzip, zet'ofill; 
h2 • custphone; 
£5 • *custno • ocustno, t'equit'ed; 
£1 • *ot'det'no • iot'det'no, t'equit'ed, revet'se, vet'ify; 
£2 • odate, default. today "y/m/d"; 
f4 • shipdate; 
f3 • agent, include. (adams, smith, jones, johnson), 
comments. "Choices at'e adams, smith, jones, ot' johnson"; 


h3 • ponum, t'equit'ed; 
x 
• backlog; 


p1 • ipat'tno • pat'tno, t'equit'ed; 
p2 • desc, t'equit'ed; 
p3 • pt'ice, include. (.10 to 5000); 
p4 • ot'det'qty; 
p5 • totalp; 
i1 • instt'uct[1,40]; 
i2 • instt'uct[41,80]; 
i3 • instt'uct[81,120]; 
i4 • instt'uct[121,160]; 


instt'uctions 


ot'det' mastet' of items; 
custOMet' mastet' of ot'det'; 


end 


Figure 21 con't. Form specification file. 


62 
INFORMIX 


PERFORM Screen-oriented Transaction Processor 


VII. 
Appendix - Error Messages 


error 2010: 


The file specified could not be opened. 
The operat- 
ing system was asked to open it for writing. 


error 2013: 


The file specified could not be opened. 
The operat- 
ing system was asked to open it tor writing. 


error 2014: 


There were an incorrect number ot arguments on the 
operating system command line. 
At least one argu- 
ment is expected. 


error 2015: 


An open comment symbol, {, was found inside an al- 
ready open 'comment on the line and character speci- 
fled. 
This could be due to a failure to close the 
previously opened comment, which was begun on the 
line and character specified. 


error 2016: 


A comment has been opened, but not closed. The last 
comment begun was opened on the line and character 
specified. 


error 2017: 


An illegal (invisible, control) character has been 
found on the line and character specified. 
It has 
been replaced by a blank in the listing, but it is 
still in the source (input) file, and should be re- 
moved before attempting to compile again. 


error 2018: 


A grammatical error has been found on the line and 
character specified. 
The construct is not under- 
standable in its context. 
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error 2019: 


This integer exceeds the maximum size allowed. 


error 2020: 


The file specified could not be opened. 
The operat- 
ing system was asked to open it for writing. 


error 2022: 


This identifier exceeds the maximum length' for iden- 
tifiers. 


error 2023: 


This quoted string exceeds the maximum length for 
quoted strings. 


error 2025: 


The comment close symbol, }, has been found on the 
line and character specified, even though no comment 
has been opened. 


error 2027: 


An illegal (invisible, control) character has been 
found on the line and character specified. 
It has 
been replaced by a blank in the listing, but it is 
still in the source (input) file, and should be re- 
moved before attempting to compile again. 


error 2030: 


A typographical error has been found on the line and 
character specified. 


error 2031: 


An internal system error. 
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error 2032: 


The number above could not be successfully converted 
to either an INTEGER or a DOUBLE or a LONG. 


error 2040: 


The file name specified exceeds the maximum length• 


•error 2041: 


The source file specified cannot be opened. 
This is 
probably because the file does not exist. 


error 2044: 


A file needed by FORMBUILD is locked by another 
user. 


error 2045: 


A file· needed by FORMBUILD is exclusively locked by 
another user. 


error 2800: 


The first line of the specification must be the key- 
word database followed by the database name. 


error 2810: 


The name specified is not an eXisting database name. 


error 2811: 


The temporary file specified could not be opened for 
wri tinge 


error 2812: 


The temporary file specified could not be read. 
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error 2820: 


The label name between brackets is incorrectly given 
or the label is missing. 


error 2830: 


A left square bracket has been found on this line, 
with no right square bracket to match it. 


error 2840: 


The label specified was not defined in the form. 


error 2850: 


The name specified is not a field name in this data- 
base. 


error 2851: 


The form has exceeded the maximum number of 
composite join pairs. 


error 2852: 


The field specified is not a composite field. 


error 2853: 


The composite field member specified is not joined 
to the proper field. 


error 2854: 


The composite fields specified do not have their in- 
dividual member fields joined in the form. 


error 2855: 


The field specified has already been specified in a 
composite join list. 
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error 2856: 


The composite fields specified cannot be joined be- 
cause they have different numbers of member fields. 


error 2857: 


There can be only one dominant composite field in a 
join list. 


error 2860: 


There is a field/value type mismatch. 


error 2870: 


The subscripted field size does not match the space 
allocated in the display field. 


error 2880: 


The word 'screen' 
(or 'page') or 'end' has been left 
out. 


error 2890: 


A screen definition must begin with a left curly 
bracket '{'. 


error 2892: 


The field name specified appears more than once. 
If 


you wish a field to be duplicated in a form, use the 
same display field label. 


error 2893: 


The display field label specified appears more than 
once in this form, but the lengths are different. 


INFORMIX 
67 


PERFORM Screen-oriented Transaction Processor 


error 2895: 


The display field length does not match the database 
field 
~ength. 
This is a warning only. 


error 2920: 


The field specified cannot be a dominant field be- 
cause it is not indexed. 


error 2921: 


The database specified is not compatible with the 
current version of INFORMIX. 
Delete the .dbd file 
and execute a DBBUILD on all your schemas. 


error 2930: 


Portions of the field specified are displayed on the 
screen more than once. 


error 2931: 


There is an error in the format specificationo 


error 2932: 


Formats may be specified only for float or double 
fields. 


error 2933: 


The format width is larger than the allocated 
display width. 


error 2934: 


The format width is less than the allocated display· 
width. 
This is a warning only. 


error 2940: 


The field specified appears both with and without 
subscripts. 


....... 
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error 2941: 


The name specified is not a display field name on 
the form. 


error 2943: 


You have exceeded the pseudo machine capacity. 


error 2950: 


The field specified has no section which starts at 
1. 
Remember that the first sUbscript is one, not 
zero. 


error 2951: 


The left and right delimiters must be specified in a 
two-character string. 


error 2952: 


In order to use a picture, the picture length must 
be the same as the display field length. 


error 2953: 


The name specified is not a database file or field. 


error 2954: 


You have exceeded the maximum of queries. 


error 2955: 


The name specified is not a displayed database field 
or displayed variable. 


error 2956: 


You may not set the display field specified to a 
value because none of its associated database fields 
belong to the same file nor is it a variable 
display-only field. 
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error 2958: 


You may have a maximum of ten parameters in a C- 
function call. 


error 2958: 


You may not set the next field as specified because 
none of its associated database field(s) belong to 
the same file. 


error 2959: 


Two files may join with a maximum of 8 field pairs, 
including all components of composite fields. 


error 2970: 


The field specified joins with other fields, but it 
is not indexed. 
PERFORM requires that join fields 
be indexed for cross-file queries. 
This is a warn- 
ing only. 
If the joined field is a member field of 
a composite join, ignore the warning. 


error 2971: 


This field is not a character field, and therefore 
cannot be subscripted. 


error 2972: 


This field cannot be right-justified or zero-filled 
because its displayed width does not match the actu- 
al field width. 
. 


error 2973:" 


There may be only one dominant field in a display 
field description. 


error 2975: 


The display field label specified has not been used. 


70 
INFORMIX 


PERFORM Screen-oriented Transaction Processor 


erro. :976: 


The end of the form has been reached prematurely. 


error 2977: 


The file specified cannot be a master of the other 
file specified because they do not join. 


error 2978: 


The fields specified cannot be joined fields because 
their types or lengths are different. 


error 2986: 


The form specification has exceeded the maximum 
number of master/detail pairs. 


error 2987: 


The form specification has exceeded the maximum of 
screens. 


error 2988: 


FORMBUILD has run out of memory. 


error 2989: 


The field specified is a reference field, but it is 
not indexed. 
PERFORM requires that reference fields 
be indexed for lookups. 


error 2990: 


The fields specified are not in the same database 
file. 


error 2991: 


Operations cannot be done on composite fields. 
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error 2992: 


The display label specified has already been used. 


error 2993: 


There is a circular join path specified in the form. 


error 2994: 


The form has exceeded the maximum number of joins 
between files. 


error 2995: 


The form has exceeded the maximum number of files 
contained in joins. 


error 3000: 


The form specified does not exist. 


error 3001: 


There are no forms in the current directory. 


error 3005: 


You do not have permission to access the form speci- 
fied. 


error 3007: 


Your form is incompatible with the current version 
of PERFORM. 
Please use FORMBUILD to re-build it, 
and then run PERFORM again. 


error 3010: 


The database specified cannot be found. 
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error 3020: 


The file specified is not in the database. 
Build 
your form again. 


error 3030: 


The field specified is not in the database. 
Build 
your form again. 


error 3035: 


The field specified has changed field type. 
Build 
your form again. 


error 3037: 


The field specified is not a composite field. 
Build 
your form again. 


error 3050: 


Operating system error. 
Cannot open a temporary 
file. 


error 3060: 


Operating system error. 
Cannot create a temporary 
file. 


error 3061: 


Cannot find user help file specified. 


error 3062: 


Cannot find help number specified. 


error 3063: 


Cannot read help file specified. 
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error 3080: 


Cannot create unique record id. 


error 3100: 


Record with a duplicate unique key exists already. 


error 3120: 


Error in field. 


error 3200: 


There are no records in the current list. 


error 3210: 


The current record position contains a deleted 
record. 


error 3260: 


This is an invalid value. 
It does not exist in the 
specified file. 


error 3261: 


Invalid value. 
Its composite value does not exist 
in specified file. 


error 3265: 


A required index on the field specified is missing. 
Add the inde x. 


error 3300: 


There are no more records in the direction you are 
going• 
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error 3400: 


There are no records satisfying the conditions. 


error 3420: 


This value is not among the valid possibilities. 


error 3430: 


This field requires an entered value. 


error 3450: 


Someone else has deleted a record which is in your 
list. 


error 3460: 


This record has been locked by another user -- try 
again later. 


error 3500: 


The two entries were not the same -- please try 
again. 


error 3600: 


No detail file has been specified for this file. 


error 3610: 


No master file has been specified for this file. 


error 3620: 


You do not have permission to write into this file. 


error 3630: 


Operating system error. 
Cannot write into a tem- 
porary file. 
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error 3650: 


You must first remove the records which join this 
record. 


error 3660: 


You must first update the records which join this 
record. 


error 3670: 


Operating system error. 
Cannot seek into a tem- 
porary file. 


error 3680: 


PERFORM has run out of memory. 


error 3681: 


Your terminal type is unknown to the system. 


error 3690: 


Detail cannot be executed -- files specified do not 
join. 


error 3700: 


Permission not granted to allow display. 


error 3710: 


'Permission not granted to allow update. 


error 3720: 


Permission not granted to allow addition of speci- 
fied record. 
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error 3730: 


Permission not granted to allow removal of specified 
record. 


error 3731: 


Cannot open the file specified. 


error 3732: 


The database specified is not compatible with the 
current version of INFORMIX. 
Delete the .dbd file 
and execute a DBBUILD on all your schemas. 


error 3750: 


Command aborted. 


error 3751: 


Type RETURN to continue. 


.' 
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I. 
Introduction 


I.A. 
What Is a Report Writer? 


ACE is a "report writer" -- a program tor pro- 
ducing reports trom the information in a database. 
ACE is a general-purpose report writer; you can use 
it to produce reports in whatever format best suits 
your application. 
The ACE report writing language 
is very flexible, and has some of the characteris- 
tics of a conventional programming language. 


I.B. 
What Is a Relational Report Writer? 


ACE is a "relational" report writer -- it al- 
lows you to combine information from more than one 
file into a report. 
The number of files from which 
you can combine information varies from 5 to 8, 
depending on certain limitations of the operating 
system and how your database is structured. 


The stores database supplied with your INFORMIX 
software provides an example of combining informa- 
tion from two files. 
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customers tile 


cname 


Brooks, B. 
Field, W. 
Robin, R. 
Hart, W. 
Court, S. 
English·, D. 


orders tile 


oname 


Brooks, B. 
Brooks, B. 
Robin, R. 
Hart, w. 
Robin, R. 
Court, S. 
Court, S. 
English, D. 
English, D. 


address 


7 Apple Rd. 
43 Cherry Ln. 
12 Heather Ct. 
65 Lark Rd. 
56 BIossom Rd. 
82 Alpine Rd. 


item 


Work Bench 
Saw 
Work Bench 
File 
Hammer 
Saw 
File 
File 
Hammer 


balance 


10.50 
0.00 
23.45 
43.00 
0.00 
0.00 


quantity 


5 
1 
3 
3 
8 
3 
5 
1 
2 


Figure 1. The stores Database. 


There are two tiles: 
the custo.ers tile which 
contains the customer's name, address and balance 
due; and the orders tile which also contains the 
customer's name, as well as an item the customer has 
ordered and the quantity ordered. 
ACE can include 
intormation trom both tiles in a report by joining 
the tiles on the customer name tield. 


A report might contain the name and address ot 
the customer "Brooks, B." as well as a list of the 
items he has on order. 
ACE can select records trom 
the custo.ers file and use the customer's name to 
look up the customer's records in the orders file. 
In order to connect two files, each file must con- 
tain a field of the same type and length that con- 
tains some identical values. 
In this example, the 
cname and onsae fields prOVide the link. 


There are three operations that ACE can perform 
when you specify what information is to be printed 
in the report. 
These operations are: "selection," 
"projection," and "join." 
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Selection is used to pick out a subset of the 
records to be included in the report. 
Projection is 
used to select the fields desired for display in the 
report. 


For example, the ACE READ statement below 
selects those records from the customers file which 
show a balance of zero. 
The ADDRESS field is not 
displayed by the projection. 


read into x 
cname, balance 
where balance = 0 
end 


The result of this READ statement is a file nx" with 
the data shown below. 


cname 


Field, 
W. 


Court, S. 
English, D. 


balance 


0.00 
0.00 
0.00 


The JOIN operation in this example is performed 
on two files. 
The file x above is 
a ntemporary 
file,n not a permanent part of the database. 
Joins 
may be performed between up to eight permanent or 
temporary files. 
In the example below, the tem- 
porary file x is utilized to gather all values for 
items that are currently on order by customers who 
have paid their bills: 


read into y 
x.cname, oname, item 
joining x.cname = oname 
end 


The list of fields can contain fields from ei- 
ther of the files that are involved in the join ex- 
pression. 
The ename field in x is differentiated 
from the cna.e that is in the customers file through 
the use of the nx.cname n syntax. 
This READ with a 
join has the effect of taking eachreeord in the x 
file and looking up the corresponding orders in.the 
orders file. 
When the value held in the field 
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x.cname is the same as the value held in the field 
oname, the two records are considered joined. 
Only 
those records which are considered joined will be 
included in the results of the READ statement. 


The results of this READ statement are shown 


below. 


cname 


Court, S. 
Court, S. 
English, 
D. 
English, 
D. 


oname 


Court,S. 
Court, S. 
English, 
D. 
English, D. 


item 


Saw 
File 
File 
Hammer 


Here the x.cna-e and ona-e fields were both 
displayed for the sake of demonstration. 
The item 
list has duplicates, as a natural result of this 
particular join process. 


The duplicates can be removed using the follow- 
ing form of the command: 


read into y 
unique item 
joining x.cname = oname 
end 


The results of this command would be as tollows. 


item 


Saw 
File 
Hammer 


To summarize: a relational report writer allows 
pieces of the database to be gathered together using 
the selection, projection and join operations. 
These operations allow you to use relationships that 
exist between data in order to gather information. 
Once the information is gathered, simple but power- 
ful report-formatting statements in the report writ- 
er allow reports containing any subset of the data- 
base to be constructed. 
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I.C. 
Structure of This Chapter 


Section II of this chapter takes an example of 


a simple report and gradually uses more and more 
features of the ACE language on it. 
Reading this 
chapter and emulating the examples with one's own 
database will teach you a great deal about ACE pro- 
gramming. 


Chapter III should be read before the examples 
are attempted. 
Chapter III is a short chapter that 
explains the mechanics of preparing and executing 
ACE programs to produce reports. 


Chapter IV describes the more advanced features 
of the language, and extends the examples of Chapter 


~III to produce reports with such features as parame- 
ter passing, user variables, and IF-THEN-ELSE state- 
ments. 


Chapter V is a more complete description of the 
ACE language. 
Programmers who expect to be doing a 
great deal of ACE programming should read this 
chapter so that they acquire a thorough knowledge of 
the language. 
Other programmers should consider 
this chapter a reference manual, which can be 
checked for other information about a particular 
feature. 


Chapter VI contains several examples which not 
only show ACE's features and give the user more pro- 
grams to emulate, but also show how a more specific 
application can be built quickly using ACE. 


Chapter VII discusses advanced applications of 
ACE, and how to apply ACE in difficult situations. 
The section includes a discussion of ACE's FOR loop 
and WHILE loop constructs, as well as the ability to 
link C subroutines into the ACE run-time system. 


Chapter VIII lists the ACE error messages. 
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II. 
Description of the ACE Language 


II.A. 
Some Typical ACE Applications 


Most computer users consider the reports that 
are written from the database to be the most impor- 
tant part of their data-processing system. 
This 
should be no surprise. 
Why else would people put 
information into a computer, if not to get it back 
out again? 
Most people use computers to store 
transactions or other items of information, and then 
to summarize the information into a report. 


Inventory control is a good example. 
Transac- 
tions such as the receipt of goods into inventory 
and taking of goods out of inventory might be 
recorded in a database. 
Such information is gen- 
erally only useful when summarized. 


Summarized inventory information might include 
a report showing the current inventory status. 
This 
would be an operational type of report, used for 
on-the-spot decision-making. 
This type of report 
might be run daily, twice a day or maybe upon 
demand. 
It might be run periodically in a 
parameterized form, to show the status for a certain 
item. 


Managers might wish to run historical reports 
indicating the average levels of certain items dur- 
ing certain time periods. 
For example, a report 
showing each item in inventory, its high shelf 
count, 
low shelf count, and average shelf count for 
the past quarter and year would be very useful in 
tracking down items that are currently understocked, 
as well as those that are overstocked. 


Generally, once managers begin to incorporate 
computer-generated reports into their operation, 
they quickly grow to depend upon the information. 
They soon want more reports, or more specific re- 
ports. 
ACE can produce these reports in a timely 
and inexpensive way. 


Mailing lists have always been a standard ap- 
plication for a database management system. 
The da- 
tabase containing the names and addresses often con- 
tains much more information. 
A mailing list main- 
tained for marketing purposes should. contain other 
information such as the product the person was in- 
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terested in, the source of the lead and what infor- 
mation has been sent. 
Other information could in- 
clude the date the customer should be contacted 
again, or what level of interest the customer 
showed. 
Using the City and/or State fields, 
a list 
of interested local customers could be generated 
weekly or daily, and sent to the sales offices for 
follow-up. 


The database could also have other files which 
contain information about products already pur- 
chased, and who purchased them. 
When a new product 
is released which might be of interest to current 
customers, it is easy to use ACE to select the names 
and addresses of the current customers. 


Since INFORMIX is a relational database, the 
name and address information need only be stored 
once. 
The other information that was just discussed 
may be stored in separate files. 
The "join" opera- 
tion of ACE's READ command may be used to link the 
information together, and gather it for the report. 
(This will be shown by example later in this 
chapter. ) 


Other typical applications for a database sys- 
tem and report writer include storing and reporting 
personnel information, medical records, all types of 
financial records, order entry, scientific laborato- 
ry statistics and Virtually any type of tracking, 
whether it be physical entities or abstract transac- 
tions. 


Many applications are sketched out in Section 
VI of this chapter. 
One particular application will 


be explored in this section for the purpose of in- 
troducing the language. 
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II.B. 
One Application - Customers and Orders 


The example database contains two files, 
customers and orders. 
The customers file contains 
the name, address, and balance of each customer of a 
store. 
The orders file contains a record for each 
order made by a customer, including the customer's 
name, the item ordered and the quantity ordered. 


The example is somewhat contrived in several 
respects. 
The customer's name would not be used as 
the unique identifier in the customers file because 
of the likely possibility of duplicate names.' 
In a 
real system, a unique customer number would probably 
be used. 
Also, the address field contains only a 
street name. 


These simplifications have been made to the ex- 
amples so that nothing gets in the way of the prin- 
ciples being demonstrated. 
The examples shown in 
Section VI are more realistic. 


12 
INFORMIX 


ACE Relational Report Writer 


II.C. 
The Simple Report 


The simplest report that can be written using 
ACE results in output that is similar to the output 
of the PRINT command of the INFORMER interactive 
query language. 
. 


A typical 
ACE session is shown on the next 
page. 
The ACE commands file, 
rep1, is created with 
an editor. 
This file is then compiled with the 
ACEPREP program. 
Finally, the report is generated 
with the ACEGO program. 


...... 
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• cat rep1 
~atabase stores end 


read orders end 


tormat every record end 


• aceprep rep1 


(Note: The output tram Beeprep is suppressed 
here and throughout this lIanual. 1 
• 


• acego rep1 


ACEGO 
ACE Report Writer Driver Read Phase 
version 
3.2 
Copyright (el 1981, 1982, 1983 Relational Database Systems, Inc. 
Sottware Slrial Number RDS-ROOOOO1 


Database Ratores- haa been selected successtully. 


The raad1ng ot the database will nov begin. 


Read statement number 1 viII now be processed. 


The reading ot the database has finished. 


ona.. 


Brooks, B. 
Brooks, B. 
Robin, R. 
Hart, 
'lI. 


Robin, R. 
Court, S. 
Court, S. 
English, O. 
English, O. 


Program over • 


ite. 


Vork Bench 
Saw 
Vork Bench 
Fl1e 
Hallllller 
Ssw 
File 
File 
Hauer 


quantity 


5 
1 
3 
3 
8 
3 
5 
1 
2 


Figure 2. A typical ACE session. 
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The program has only three commands, 
DATABASE, 
READ and FORMAT. 
Every ACE program must have at 
least these three commands. 
All others, such as the 
SORT command, are optional. 


The DATABASE command defines the name of the 
database that is being accessed. 
The READ command 
has the same structure as the READ command of the 
INFORMER query language, with some additional op- 
tions. 
In the case of the simple report above, the 
READ command is asking tor all of the records in the 
file and all of the fields in these records. 
Notice 
the INTO X clause is missing. 
A single READ state- 
ment used in ACE does not need to create a temporary 
file. 
This is called an "optimized read." An 
optimized read saves disk space. 
It does not neces- 
sarily make a query run faster. 


The FORMAT command, in this case, is asking for 
the "default" formatting of the records. 
Default 
formatting in ACE is exactiy the same as the default 
formatting in INFORMER. 
If the field names and 
their data can fit on the page when printed across, 
then the report will be printed with columns, as 
above. 
Otherwise, the field names and data will be 
printed going down the page, one field per line. 


ACE output directed to a printer assumes a 
132-character page width, the size of wide line 
printer paper. 
This can be changed using the op- 
tional OUTPUT command, as will be seen later. 
The 
default page width of ACE reports to the screen (and 
of INFORMER throughout) is 80 characters. 
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11.0. 
Data Selection 


The READ command of the ACE language is identi- 
cal to the READ command in INFORMER. 
In the example 
below, only the item and quantity fields are speci- 
fied for the report. 


_ cat rep2 
database stores end 


read 


item quanti ty 
end 


format every record end 


_ ace prep rep2 


_ acego rep2 


ACEGO 
ACE Report Writer Driver Read Phase 
version 
3.2 
Copyright (C) 1981, 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-R000001 


Database "stores" has been selected successfully. 


The reading of the database will now begin. 


Read statement number 1 will now be processed. 


The reading. of the database has finished. 


item 


Work Bench 
Saw 
Work Bench 
File 
Hammer 
Saw 
File 
File 
Hammer 


Program over. 
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5 
1 
3 
3a 
3 
5 
1 
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This report 
al~v use$ FORMAT EVERY RECORD to 
specify the default. 


The next example shows how the READ command's 
syntax can be used not only to project which fields 
are to be included in the report, but also to select 
which records are to be read. 
In this case, only 
the records that have a quantity field with a value 
greater than 2 are selected for printing in the re- 
port. 


ACE programs may have several READ commands. 
A 
READ command can use the results of prior READ com- 
mands, if they are put into a temporary file. 
If 


only one READ statement is used, then no temporary 
file need be constructed when the report is run. 
If 
more than one READ statement is used, only the 
fields in the field list of the last READ statement 
will be formatted by the FORMAT command. 


The ACEGO program prints a good deal of infor- 
mation about the preparation of the report before it 
actually starts printing the report itself. 
This is 
useful when the report is first being developed or 
when the status of the program being prepared is of 
interest. 
These messages will also contain any 
warnings about the need for additional indexes to be 
created for the report to run efficiently. 


However, when the report has been written and 
tested, it may be desirable to have the ACEGO pro- 
gram "be quiet" with regard to these messages. 
The 
-q flag can be used just after ,the ACEGO command to 
suppress system messages. 


The -q flag will be used With most of the 
remaining examples. 


~ cat rep; 
database stores end 


read 
item quantity 
where quantity> 2 
end 


format every record end 
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~ aceprep 
~ep3 


~ scego -q rep; 


item 


Work Bench 
File 
Saw 
Work Bench 
File 
Hammer 
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quantity 


; 
; 
; 
5 
5 
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II.E. 
Sorted Output 


The records in a report will not be printed in 
any particular order unless the SORT command is em- 
ployed. 
The SORT command should come after the last 
READ command, as shown below. 


:c cat rep4 
database stores end 


read into x orders end 


sort by item, quantity end 


f?rmat every record end 


:c aceprep rep4 


:c acego -q rep4 


oname 


English, 
D. 
Hart, W. 
Court, S. 
English, 
D. 
Robin, R. 
Brooks, B. 
Court, S. 
Robin, R. 
Brooks, B. 


INFORMIX 


item 


File 
File 
File 
Hammer 
Hammer 
Saw 
Sa.., 
Work Bench 
Work Bench 


quantity 


1 
3 
5 
2 
8 
1 
3 
3 
5 


19 


.' 


ACE Relational Report Writer 


The above SORT command calls for the records to 
be sorted by the item field. 
However, in the case 
of this report, there were three records where the 
item was "File". 
Since the SORT command in this ex- 
ample asked for the records to be sorted by item, 
and then by quantity, the quantity fields are sorted 
in increasing order, within each group of items. 


This concept is known as a "hierarchical sort." 
There may be from one to eight fields (having field 
length definitions totaling 120 characters) involved 
in the SORT command. 
In other words, there may be 
up to eight levels in the sorting hierarchy. 


Each one of the fields listed in a SORT command 
may be sorted in ASCENDING or DESCENDING order. 
In 
the example, both the item and quantity fields have 
been sorted in ASCENDING order (the default). 
How- 
ever, if the sort order for the quantity field was 
specified to be DESCENDING, the item field could 
still be left ASCENDING. 
Then the report would have 
listed the records in alphabetical order by item, 
but the records would be listed in descending order 
by quantity within each group of items. 


Two ways of doing this with the SORT command 
are shown below. 


sort by item quantity descending end 


or 


sort by item ascending quantity descending end 


Fields in field lists such as in the SORT and 
READ statements may be separated by one or more 
blanks, or a comma or the word AND. 
The choice of 
separator' is purely cosmetic. 
Users may choose 
among the eqUivalent syntaxes shown below. 


sort by item quantity end 
sort by item, quantity end 
sort by item and quantity end 


SUbscripted sorting on character fields is dis- 
cussed in Section IV.F. 
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II.F. 
Custom Formatted Output 


Much of the usefulness of ACE comes from the 
capabilities of the FORMAT command. 
This command is 
used to indicate with precision the exact position 
of the data and headings on the report's pages. 
The 
FORMAT command was designed to be extremely flexi- 
ble. 
Not only is it easy to produce columnar re- 
ports, as have been shown, but reports with unusual 
formats, such as payroll checks, invoices, and mail- 
ing labels can easily be produced as well. 


Some of the simple columnar reports will be 
shown in this section: the non-columnar reports are 
shown in examples later in the chapter. 


Another major capability of the FORMAT command 
is arithmetic. 
All of the standard "calculator" 
functions are available in the FORMAT command. 
Any 
arithmetic value, or result of a calculation, may be 
printed in a variety of formats using the PRINT US- 
ING syntax (discussed in more detail later). 
"Ag- 
gregate" calculation functions, such as TOTAL, 
AVER- 
AGE, MIN, 
MAX, 
PERCENT, and COUNT are also available 
to be printed, or used in more complex calculations. 
These will also be discussed in more detail later. 


Sorted data is naturally grouped by content. 
For example, when sorting is performed on the item 
field, all of the records containing the value 
"File" are grouped together, as are the records con- 
taining "Hammer", 
"Saw", etc. 
This natural grouping 
can be exploited so that the prlnting of summary in- 
formation can be requested after each group of 
records. 
Just as the sorting of records may occur 
on a hierarchical basis, the grouping of the records 
can be controlled according to the same hierarchy. 


These advanced features will be introduced 
separately. 
The general structure of the FORMAT 
command will now be discussed. 


The FORMAT command is broken down into clauses. 
At least one clause must be contained in the FORMAT 
command. 
The clauses contain statements. 
The fol- 
lOWing example has a FORMAT command with two 
clauses, the PAGE HEADER clause and the ON EVERY 
RECORD clause. 
(An automatic two-field sort may be 
accomplished without the use of a temporary file by 
creating a composite key, composed of the two 
fields. ) . 


o' 
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~ cat rep5 
database stores end 


read into x orders end 


sort by item, quantity end 


format 


page header 
print "Sorted and Grouped Item List" 
skip 2 lines 


on every record 
print item, 8 spaces, quantity 


end 


~ aceprep rep5 


~ acego -q rep5 


Sorted and Grouped Item List 


File 
File 
File 
Hammer 
Hammer 
Saw 
Saw 
Work Bench 
Work Bench 


1 
:3 
5 
2 
8 
1 
:3 
:3 
5 


The statements in the PAGE HEADER clause dic- 
tate what printing is done on the top of every. page. 
In this particular page header clause there are two 
statements, a PRINT statement and a SKIP statement. 
The PRINT statement, in this case, is just printing 
a heading. 
The SKIP statement is providing the 
blank lines between the heading and the body of the 
report. 
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The statements in the ON EVERY RECORD 
~lduse 


are printing the body of the report. 
Data process- 
ing jargon refers to these as "detail" lines, or the 
"detail" printing in the report. 
Detail printing is 
any printing other than headers, trailers, subtotals 
or grand totals. 
This terminology fits the columnar 
report model quite well, but really does not mean 
much if the report prints only totals, or prints 
specifically formatted output, such as packing slips 
or time cards. 


There are several other clauses that print in- 
formation in the report. 
The clauses are listed 
here. 


PAGE HEADER 
FIRST PAGE HEADER 
ON LAST RECORD 
PAGE TRAILER 
ON EVERY RECORD 
BEFORE GROUP OF field 
AFTER GROUP OF field 


At least one of these clauses must be used in 
the FORMAT section of a report. 
(Otherwise, nothing 
would be printed.) 
You may use all of them if 


desired. 


The PAGE HEADER clause has just been seen. 
If 
there is a need to print something different at the 
top of the first page, then a FIRST PAGE HEADER 
clause can also be used. 
If there is no FIRST PAGE 
HEADER clause, then the first page will contain the 
same heading as allot the other pages in the re- 
port. 


The PAGE TRAILER clause allows you to specify 
printing for the bottom of each page in the report. 
There is no special form of the PAGE TRAILER clause 
for the first page of the report, but the ON LAST 
RECO~D clause will control printing at the very end 
of the report. 
It is convenient to put "grand to- 
tal" printing in this clause, tor output at the end 
of the report. 


If printing is to be done tor each record that 


was qualified by the last READ statement, then this 
printing should be triggered by the ·ON EVERY RECORD 
clause. 
It is not unusual to have a report that 
only has printing triggered by the ON LAST RECORD 
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clause, or have printing triggered before or after a 
group of records with the BEFORE GROUP OF or AFTER 
GROUP OF clauses. 


The statements that may be used in any FORMAT 
clause (except where specified) are listed below. 


print 


skip n lines 


skip to top of page 
(cannot be used in headers or 
trailers) 


if then 


if then else 


pause "User defined prompt string." 


(cannot be used in headers or 
trailers) 


(when used in headers and 
trailers number of lines of 
output must be identical) 
let variable 
2 expression 


while exp do statement 


for var • exp to exp (step exp) do statement 


call croutine(parameterlist) 


croutine(parameterlist) 


The PRINT statement is by far the most used, 
and most powerful, of the statements. 
It allows one 
or more items to be printed per PRINT statement. 
Each statement will print one line in the report. 
If a PRINT statement is terminated with a semi- 
colon, its printing of a newline will be suppressed. 
This allows several PRINT statements to be used to 
print one line of output. 


Items that can be printed include any field, 
quoted strings of characters, blank spaces or the 
result of numeric calculations. 
Whenever anything 
that is numeric is printed, the PRINT USING syntax 
can be used to format the number for the report. 
(See the section "Printing Numeric Fields and Ex- 
pressions.") 
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Tl.",. ~ 
a~e options available 
fo~ the PRINT 
statement, such as WITHOUT TRAILING BLANKS. 
WITHOUT 
TRAILING BLANKS may be 
abb~eviated as CLIPPED. 


In addition, the date and the time a 
~epo~t be- 
gins running can be 
p~inted automatically. 
Today's 
date is also available with the TODAY 
keywo~d. 


The statements and options 
fo~ PRINT statements 


a~e discussed 
mo~e completely in 
Sec~ion V.I. 
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II.G. 
Performing Calculations 


The next example shows the PRINT statement with 
the USING syntax. 
The report is the same as the 
last example, except the ON LAST RECORD clause is 
used to trigger a SKIP statement and a PRINT state- 
ment. 
This PRINT statement will print the total of 
the quantity field, 
summed from all of the records. 
To do this, the TOTAL aggregate is also used. 


% cat rep6 
database stores end 


read into x orders end 


sort by item, quantity end 


format 


page header 
print "Sorted and Grouped Item List" 
skip 2 lines 


on every record 
print item, 8 spaces, quantity 


on last record 
skip 2 lines 
print "There were a total of ", 
total of (quantity) using "<,«<" 
print "items ordered." 


end 


%" aceprep rep6 
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~ acego -q rep6 


Sorted and Grouped Item List 


File 
File 
File 
Hammer 
Hammer 
Saw 
Saw 
Work Bench 
Work Bench 


There were a total of 31 
items 
ordered~ 


1 
3 
5 
2 
8 
1 
3 
3 
5 


The less than symbol «) on the PRINT USING 
statement causes ACE to left-justify numbers. 
The 
TOTAL aggregate is much more flexible than shown 
here. 
TOTAL, MIN. 
MAX, or AVERAGE may operate on 
more than just one field. 
Here only the quantity 
field was totalled. 
If there had been a field con- 
taining the price of the items, the TOTAL aggregate 
could have .been made to operate on the product, as 
follows. 


total of quantity * price 


In fact, any arithmetic expression, involving 
numbers or fields, 
may be used as the "argument" of 


an aggregate expression. 


Any of the six aggregates, TOTAL, 
AVERAGE, MIN, 
MAX, PERCENT, or COUNT may be "qualified" with a 


, 
WHERE clause: 


total of quantity where quantity> 2 


This is to say that even though the READ state- 
ments may have qualified a certain subset of the 
records in the database for use in the report, each 
aggregate itself may be qualified further. 


The PRINT USING syntax shown in this example 
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uses the "<,, character to indicate that the number 
should be left-justified in a print field that is 
only as long as the number. 
Another typical format- 
ting character is the pound sign (#), which means to 
right-justify the number in a fixed length field the 
same size as the PRINT USING "format string." 
If 
the number is not big enough to fill the string, the 
"N" format character specifies that the rest of the 
spaces in the print field should be filled with 
blanks. 


There are other format characters. 
For exam- 


p~e, the "*" character would indicate that any un- 
filled character positions in the print field should 
be filled with asterisks (*). 
This is useful when 
checks are being printed. 


Commas in the PRINT USING format atring indi- 
cate where commas should be placed if the number is 
large enough to need them. 
The commas are optional. 
(See Section V. 1. 2 for examples • ) 
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II.H. 
Grouping the Data in the Report 


In the orders file used in these examples, 
there are three records which have a "File" for the 
item field, 
2 "Hammer" records, 2 "Saw" records and 
2 "Work Bench" records. 
If the records are printed 
by an ACE program that does not have a SORT command, 
they will be printed in random order. 
If they are 
sorted by the item field, they are not only printed· 
in that order, but they are also grouped by item. 


This natural grouping of records with duplicate 
values that 'occurs during the sorting process can be 
exploited using the FORMAT command of ACE. 
State- 
ments may be placed in the BEFORE GROUP OF clause or 
the AFTER GROUP OF clause to print blank lines, sub- 
totals, sub-headers, or trailers. 
An example of 
this is shown below. 
. 


% cat rep? 
database stores end 


read into x orders end 


sort by item, quantity end 


format 


page header 
print "Sorted and Grouped Item List" 
skip 2 lines 


on every record 
print item, 
8 spaces, quantity 


after group of item 
skip 1 line 


on last record 
skip 2 lines 
print "There were a total of ", 
total of (quantity) using "#,1"" 
print "items ordered." 


end 


% aceprep rep? 
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~ acego -q rep7 


Sorted and Grouped Item List 


File 
1 
File 
3 
File 
5 


Hammer 
2 
Hammer 
8 


Saw 
1 


Saw 
3 


Work Bench 
3 
Work Bench 
5 


There were a total of 
31 
items ordered. 


Here a very simple AFTER GROUP OF clause is 
used to print a separation line between the groups 
of duplicate item values. 


An additional form of the aggregate values TO- 
TAL, 
AVERAGE, MIN, MAX, 
COUNT and PERCENT by group 
is available in the AFTER GROUP OF clauses. 
Group 
aggregates (GROUP TOTAL, 
GROUP AVERAGE, etc.) can 
only be used in the AFTER GROUP OF clause for the 
group they reference. 
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~ cat repS 
database stores end 


read into x orders end 


sort by item, quantity end 


format 


page header 
print "Sorted and Grouped Item List" 
skip 2 lines 


on every record 
print item, 
8 spaces, quantity 


after group of item 
skip 1 line 
print "There were a total of 
", 
group total of (quantity) using "H#,###" 
print item without trailing blanks, 
" items ordered." 
skip 1 line 


on last record 
skip 2 lines 
print "There were a total of ", 
total of (quantity) using "#,H#H" 
print "items ordered." 


end 


~ aceprep repS 
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~ acego -q rep8 


Sorted and Grouped Item List 


File 
1 
File 
3 
File 
5 


There were a total of 
9 
File items 
o~dered. 


Hammer 
2 
Hammer 
8 


There were a total of 
10 
Hammer items ordered. 


~w 
1 
Saw 
3 


There were a total of 
4 
Saw items ordered. 


Work Bench 
3 
Work Bench 
5 


There were a total of 
8 
Work Bench items ordered. 


There were a total of 
31 
items ordered. 


The GROUP TOTAL aggregate is very different 
from the "global" TOTAL aggregate. 
The GROUP TOTAL 
will calculate a total based only upon the records 
in the most recently processed group. 
However, 
group aggregates may be further qualified with a 
WHERE clause. 
The argument of the group aggregate 
can be any arithmetic expression, and not just one 
arithmetic value, such as the field quantity. 


The only exception to this is that aggregates 
may not be nested in expressions. 
That is, the 


32 
INFORMIX 


......; ..,.. 


ACE Relational Report Writer 


value of an aggregate cannot be dependent on the 
value of another aggregate used in the same expres- 
sion. 
The statements below are invalid because ag- 
gregates are nested. 


Incorrect Statements: 


total of (average of (quantity) 
+ 5) 


average of (quantity) 
where (quantity> average of (quantity» 
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II. I. 
Using Data .tro. More than One File 


The ACE relational report writer can produce 
reports that incorporate data from more than one 
file. 
The syntax to do this is the same as in the 
INFORMER query language: 


• cat rep9 
database stoNe end 


outlNlt 
lett ..r&1n,0 
right urg1n eo 
end 


re.d 


cueto..rs 1te. quantity 
joining en... • ona.. 
end 
tor.at e.ery record end 


• aceprep rep9 


• aeeso -q rep9' 


cne.e 
address 
balance i te. 
quantity 


Broooks. B. 
7 Apple Rd. 
10.50 York Bench 
S 
Brooks. B. 
7 Apple Rd. 
10.50 Saw 
1 
Robin. R. 
12 Heather Ct. 
23.45 York Bench 
:5 


Robin. R. 
12 Heather Ct. 
23.45 Hallmer 
a 
Hart. V. 
65 Larok Rd. 
43.00 File 
:5 


Court. S. 
56 BlosllO. Rd. 
0.00 Saw 
:5 


Court. S. 
56 Blossoll Rd. 
0.00 File 
S 


EngHsh. D. 
82 Alpine Rd. 
0.00 File 
1 


English. D. 
82 Alpine Rd. 
0.00 Ha_r 
2 


This example contains a READ command which 
specifies all of the tields from the custo.ers file, 
but only the ite. and quantity fields from the 
orders tile. 
This is the Wprojection" operation. 
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Since the READ statement is asking for fields 
from two different files, it must specify how the 
two files are to be put together. 
The phrase JOIN- 
ING CNAME = ONAME tells ACE to take a record from 
the customers file, and look up all of the records 
in the orders file which have the same name in them. 
Since the cnsme field has unique values in it, this 
is th$ same as attaching the customers records to 
the front of all of the orders records, matching on 
the customer's name. 


This example also introduces the OUTPUT com- 
mand, which allows you to override the ACE defaults 
for left, right, top, and bottom margins, as well as 
the page length and where the report is to be 
displayed or printed • 
. 
The OUTPUT command must be the first statement 
section in the ACE report specification. 
In order 


for OUTPUT to have any effect, it must precede the 
READ section. 
The OUTPUT command is discussed in 
greater detail in Section V.E. 


The next example uses a READ statement to 
select a subset of the records in the customers 
file, and then to find the corresponding orders for 
these custo.ers. 


% cat rep10 
database stores end 


output 
right margin 80 
end 


read 
cname, balance, item 
where balance > 10.00 
joining cname = oname 
end 


format every record end 


%aceprep rep10 
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~ acego -q rep10 


cname 


Brooks, B. 
Brooks, B. 
Robin, R. 
Robin, R. 
Hart, 
W. 


balance 


10.50 
10.50 
23.45 
23.45 
43.00 


item 


Work Bench 
Saw 
Work Bench 
Hammer 
File 


The "Where Clause" in the READ statement 
selects all of the records with a balance greater 
than ten dollars and projects the c~ and balance 
fields from the custo.ers file and the lte. field 
from the orders file. 
The "joining" clause joins 
the custa.ers and orders file on the cnaae and onaae 
fields. 
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III. 
How To Write and Run ACE Programs 


III.A. 
Preparing an ACE Program 


ACE is composed of two programs, ACEPREP and 
ACEGO. 
The ACEPREP program translates the ACE pro- 
gram and creates a file that has .arc as the last 
four characters of the file name. 
This file con- 
tains the Ace Report Control tables, thus the acro- 
nym "arc." 


To prepare an ACE program for execution, use an 
editor to create an operating system file containing 
the ACE commands. 
This file is then translated, or 
"compiled" by ACEPREP with the following command. 


~aceprep filename 


When the file has been compiled successfully, the 
run-time program ACEGO is used to create the report. 


The following is an example of the steps in 
preparing an ACE program to print the orders file in 
sorted order by oname, with one blank line separat- 
ing each group. 


First, one of the operating system's text edi- 
tors is used to create this file and name it 
ordersrep. 
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~ cat oraersrep 
database stores end 


read into x oname, item end 


sort by oname end 


frllat 


page header 
print "Sorted and Grouped Nalle List" 
skip 2 lines 


on every record 
print oname, 2 spaces, item 


after group ot oname 
print 


end 


Then ACEPREP is run using the tollowing com- 
mand • 


• aceprep ordersrep 


ACEPREP 
ACE Report Writing Language Compiler 
version 
3.2 


Copyright (C) 1981, 1982. 1983 Relational Database Systems, Inc. 
Softvare Serial Number RDS-ROOOOO1 


The file ·ordersrep· viII nov be compiled. 


The compilation vas not successful. 
Errors found: 1. 


The file ·ordersrep.err· has been vritten. 


Program over. 


After the execution of this command, one of two 
tiles is created by ACEPREP. 
~he file ordersrep.arc 
is created when no compilation errors occur, and the 
tile ordersrep.err is created when compilation er- 
rors do occur. 
In either case, the ordersrep ACE 
specification file is lett unchanged. 
As shown 
above, there was a programming error in the program, 
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so the ACEPREP compiler generated an error listing 
in a file called ordersrep.err, and did not create 
the arc file, ordersrep.arc. 
This error listing is 
shown below. 


% cat ordersrep.err 
database stores end 


read into x oname, item end 


sort by oname end 


frmat 
.. 


A grammatical error has been found on line 7, 
character 1. 
The construct is not understandable 
in its context. 
See error number 8018. 


page header 
print "Sorted and Grouped Name List" 
skip 2 lines 


on every record 
print oname, 2 spaces, item 


after group of oname 
print 


end 


The error listing points to a spelling error in 
the word "format. 
The ACEPREP compiler cannot 
translate the program unless all of the "reserved 
words", such as "format," are spelled correctly. 
Once the spelling error is fixed, the file ordersrep 
can be compiled again. 
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• eat ordersrep 
database stores end 


read into x oname, item end 


sort by oneill! end 


tOl'mat 


page header 
print ·Sorted and Grouped Name List· 
skip 2 11nes 


on every record 
print oneme, 2 spaces, item 


aEter group ot onallltt 
print 


end 


• aeeprep ordersrep 


ACEPREP 
ACE 
Repo~t Writing Languaga Compiler 
veraion 
3.2 


Copyright (C) 1981, 1982, 1983 Relational Database Syste.s, Inc. 
Sottvare Serial Number RDS-ROOOOO1 


The tile ·ordersrep· viII nov be compiled. 


The compilation vas successtul. 
The tile that holds 


the ACE Report Control tables, "ordersrep.are", has been created. 


Program, over. 


-.' 
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III. B. 
Running an ACE Program 


Once the program 1s compiled, it can be run at 
any time by using the program's base name and the 
ACEGO run-time program. 


~ acego -q ordersrep 


Sorted and Grouped Name List 


Brooks, B. 
Work Bench 
Brooks, B. 
Saw 


Court, S. 
Saw 


Court, S. 
File 


English, D. 
File 
English, D. 
Hammer 


Hart, 
W. 
File 


Robin, R. 
Work Bench 
Robin, R. 
Hammer 


You use ACEGO with the tile name alone, without 
the extension .arc, even though the intermediate 
file ACEPREP creates is called ordersrep.arc. 
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IV. 
Descrip~ion o~ Advanced 
rea~ures 


IV.A. 
Pr1n~ing 
~be 
Da~ and Tille 


The date and time of the running of the report 
can be printed using the keywords DATE and TIME (en- 
closed in commas) in a PRINT statement. 
Here is an 
example: 


print "The date of the running of this report" 
print "is ",date,"." 
skip 2 lines 
print "The time of the running of this report" 
print "is ",time,"." 


When this series of PRINT statements executes 
in any of the clauses of the FORMAT command, the 
result would be as follows. 


The date of the running of the report 
is Mon Aug 10 1981. 


The time of the running of this report 
is 10:14:44. 


The date and time are supplied by the operating 
system when the DATE and TIME keywords are used, in 
the formats shown above. 
You can use a subscript to 
refer to the elements of date and time by position 
number, in the same way as you would SUbscript any 
other character variable. 


The day of the week and the number of the day 
could be printed by subscripting the date keyword: 


print "The day of the week is ", 
date[1,3], " ", date[9,10J 


In the bracketed subscript, the numbers "1,3" refer 
to the position of the name of the day in the date, 
and "9,10" reference the position of the number of 
the day in the date format. 


The TODAY keyword also prints the current date. 


print "Today's date is 
ft, today 
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You can 
mah~;~late elements of dates that are 
data items entered into database files with the date 
functions: 
DAY, 
MONTH, 
YEAR, and WEEKDAY. 
These 
functions are discussed in Section V.J. 
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IV.B. 
Reports Using Paraaeters 


When several reports that will use the same 
output format are desired from a database, only one 
set of report specifications should be written. 
The 
report specifications can use ACE's parameter facil- 
ity so that the user can specify fields from the da- 
tabase at the time of running a particular report. 


ACE provides two different ways for a user to 
communicate one or more parameters to a report as it 
begins running. 
The first way allows the parameters 
to be typed on the command line. 
If a report named itearep1 were parameterized 
for an item name, it could be run selectively for 
the item "File" in the following fashion. 


~ acego -q itemrep1 File 


To run the report for a parameter that has more 
than one word, use the following syntax: 


~ acego -q itemrep1 "Work Bench" 


That is, parameter values that include blanks 
should be surrounded by double quotation marks when 
they are given as parameters on the command line. 


A parameter is specified with the keyword 


"param" and a number, a parameter name, and a field 
definition, as in: 


param(1] selectitem type character length 20 


The program to utilize these parameters and the 
output of the selection for the item File are shown 
following. 
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~ cat itemrep1 
database stores end 


define 
param[1] selectitem type character length 20 
end 


read orders 


where item. selectitem 
end 


format every record end 


~ aceprep itemrep1 


~ acego -q itemrep1 File 


oname 


Hart, 
W. 


Court, S. 
English, D. 


item 


File 
File 
File 


quantity 


3 
5 
1 


Parameter field definitions are specified with 
the DEFINE command. 
A DEFINE command should be 
placed before the READ section in the ACE report 
specification file. 


The parameter field definition(s) should match 
that of the field being parameterized. 


Reports can use more than one parameter. 
Up to 
100 parameters can be accepted from the command line 
by an ACE report program. 
Below is a program that 
selects all of the orders records for a report that 
is parameterized with an ite.. 
Another parameter, 
selectquantity, is also specified. 
The report has a 
READ command that uses both the item and quantity 
parameters to select records with a particular item 
that have a quantity above a certain value. 
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• cat itemrep2 
database stores end 


define 
param[1] selectitem type character length 20 
param[2] selectquantity type integer 
end 


read 
into x 
orders 
where item. selectitem 
and quantity> selectquantity 
end 


format every record end 


• acego -q itemrep2 File 2 


oname 


Hart, W. 
Court, s. 


item 


File 
File 


quantity 


3 
5 


Parameterizing information can also be sent to 
a running ACE program using the INPUT command with a 
PROMPT FOR clause. 
This command can be used to 
print a prompt to a user's terminal, and interac- 
tively initialize an ACE variable. 
This variable 
can then be used in the statements of the ACE pro- 
gram. 


The following program prompts for both the ite. 
value and the quantity value. 
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~ cat pitemrep2 
database stores end 


define 
variable inputitem type character length 20 
variable inputquantity type integer 
end 


input 
prompt for inputitem using 
"Type ITEM for selection > " 
prompt for inputquantity using 
"Type QUANTITY for selection > " 
end 


read 
into x 
orders 
where item = inputitem 
and quantity> inputquantity 
end 


format every record end 


~ aceprep pitemrep2 


~ acego -q pitemrep2 


Type ITEM for selection > File 


Type QUANTITY for selection > 2 


oname 


Hart, W. 
Court, S. 


INFORMIX 


item 


File 
File 


quantity 


3 
5 
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IV.C. 
Using Variables 
~or Subcalculations 


Numeric values to be printed in reports may not 
always result directly from arithmetic combinations 
of fields, constants, and aggregates. 


For example, the COUNT aggregate vill report 
the total number of records selected for printins in 
the report. 
The GROUP COUNT is available after (and 
only after) a group of records has been processed, 
and it contains the number of records that vere in 
the most recent group. 
Hovever, there is no aggre- 
gate to print a cumulative count of records in all 
of the preViously printed groups. 
This 1s also true 
for running subtotals of a field. 


The following example vill use a variable to 
keep a running subtotal of the number of items or- 
dered and will print this running subtotal after 
each group of records has been processed. 
The cal- 
culations requested vhen the group changes (AFTER 
GROUP OF) are performed at the ftcontrol breakft -- 
control of the operation passes to a new group. 


Variables are named and defined vith a DEFINE 
statement. 
As mentioned, the DEFINE statement must 
precede the READ section. 
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~ cat runningtot 
database stores end 


define 
variable runningtotal type integer 
end 


read into x orders end 


sort by item, quantity end 


format 


first page header 
let runningtotal = 0 
print "Sorted and Grouped Item List" 
skip 2 lines 


page header 
print "Sorted and Grouped· Item List" 
skip 2 lines 


on every record 
print item, 8 spaces, quantity 
let runningtotal 
= runningtotal 
+ quantity 


after group of item 
skip 1 line 
print "There were a total of 
", 
group total of (quantity) using "1,1"" 
print item without trailing blanks, 
" items ordered." 
print "This totals ", 
runningtotal using ",,#"", 
" thus far." 
skip 1 line 


on last record 
skip 2 lines 
print "There were a total of 
", 
total of (quantity) using "1,1"" 
print "items ordered." 


end 


~ aceprep runningtot 
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%acego -q runningtot 


Sorted and Grouped Item List 


File 
1 
File 
3 
File 
5 


There were a total of 
9 
File items ordered. 
This totals 
9 thus far. 


Hammer 
2 
Hammer 
8 


There were a total of 
10 
Hammer items ordered. 
This totals 
19 thus far. 


Saw 
1 
Saw 
3 


There were a total of 
4 
Saw items ordered. 
This totals 
23 thus far. 


Work Bench 
3 
Work Bench 
5 


There were a total of 
8 


Work Bench items ordered. 
This totals 
31 thus far. 


.. 


~.. 


50 


There were a total of 
items ordered. 
31 


INFORMIX 


ACE Relational Report Writer 


The variable runnlngtotal was defined in the 
DEFINE command as an integer. 
DEFINE statements use 
the same data types as DBBUILD, and the syntax to 
define them is the same as it is in DBBUILD, except 
that you cannot use abbreviations for data type 
names (e.g., 
CHAR or LEN). 
There can be up to 100 
user-defined variables. 


The variable is given an initial value of 0 in 
the FORMAT section, after the READ section. 
The LET 
statement that assigns a value to a variable usually 
occurs in the FORMAT section, with the first assign- 
ment made after the PAGE HEADER or 
F~T PAGE HEADER 
statement. 
It is legal to 
a~sign values to variables with 


LET outside of the FORMAT section, but in that case 
the assignment statement must be terminated with the 
word END like any other statement. 


The result of this report specification with 
DEFINE and LET for the runningtotal variable is that 
just before the group total is printed, a cumulative 
group total is added to the runningtotal variable. 


A LET statement can have any numeric or string 
expression on its right-hand side. 


Here are some other valid LET statements: 


let pr int_line .. "This is my name: ", cname 


let save_this 
= "This is how much I owe: ", 
balance using "$,$$$.##" 


let save_tot = group total of balance 


let my_total = «gr'oup total of balance) * 4.36) -1 


When LET is used to assign values to a user 
. 
variable that has been DEFINEd as a character type 
variable, 
LET statements can be used to save lines 
of text that can later be printed with PRINT state- 
ments. 
(See also Section IV.K). 
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IV.D. 
Controlling Printing with IF-THEN-ELSE 
State.ents 
:- 


'fhe READ commands and the various clauses of 
the FORMAT 
~ommand allow the ACE programmer to con- 
trol the 
cont~nts of an ACE report. 
However, there 
are situations where the decision of what to print 
must be made conditionally. 
In this case, the IF- 
THEN-ELSE statement may be helpful. 


In an IF-THEN-ELSE statement, the number of 
statements between the BEGIN and END keywords can be 
unlimited. 
A statement does not have to have an 
ELSE part. 
IF-tHEN-ELSE statements may also be 
nested. 
IF-THEN-ELSE statements can control other 
IF-THEN-ELSE statements, and there is no limit to 
the depth to which IF-THEN-ELSE statements may be 
nested. 
If 
IF-THEN~ELSE statements that contain print- 
ing statements are used in PAGE HEADER or PAGE 
TRAILER clauses, care should be taken that both the 
IF-part and the ELSF.-part will print out the same 
number of lines. 
They may be used in other clauses 
without this consideration. 


There are examples of several varieties of IF- 
THEN-ELSE statements in Section V. 
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IV.E. 
Optimized 
Pe~to~.ancc 


The READ commands of both INFORMER and 
ACE will 
analyze the available indexes before attempting to 
satisfy a query. 
If system messages are turned on 
(i.e., -q is not being used), 
ACE and INFORMER will 
inform the user when indexes can be used on the 
fields involved in a query. 
If indexes cannot be 
used, the records in the file will be scanned 
sequentially. 


When a READ command contains a JOIN operation, 
the field on the right-hand side of the JOIN should 
be indexed. 
If not indexed, the retrieval will be 
performed more slowly. 


READ commands can create temporary files. 
A 
data structure representing this temporary file is 
actually constructed on the disk. 


When operations are expressed in one READ 
statement, 
ACE does not require temporary files (the 
INTO phrase can be omitted). 
This Poptimized READP 


can save disk space, which is useful when reports 
involve a large part or the entirety of a file. 


For example: 


read customers end 


read customers and orders 
joining cname = oname 
where balance = 0 end 


An 
optimi~ed 
READ can also be used at the end 
of a series of READ statements by omitting the 
INTO 
X phrase from the last READ statement. 


. If an ACE report is to be sorted by more than 
one field, the optimized read is possible only if 
the sort fields have been defined as a composi te 
key. 
This definition is done in the schema. 
Defin- 
ing a composite key means that no temporary files 
need be created when a multi-level sort is speci- 
fied. 


There are, however, three restrictions connect- 
ed with using a composite field to avoid creating a 
temporary file for a multi-level sort: 


--.. 
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• 
The filename must be given in the READ state- 
ment, rather than a list of individual fields. 
This means that all the fields from the data- 
base will be displayed. 


• 
The first field specified for the sort must not 
be a primary key. 


• 
You must specify the sort by listing the indi- 
vidual field names of the composite field rath- 
er than the name of the composite field. 
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IV.F. 
Subscripting 
Sort~ng 


Another approach to sorting is by subscripting 
character fields. 
When dates are defined as charac- 
ter fields, you can use a subscript that refers to 
the character positions of the date. 
This enables a 
sort by month, day, or year. 
(Dates stored as one 
of the three date types can be sorted only by day.) 


The optional separators between parts of a date 
also have position numbers when a date is defined as 
a character field. 


For example, a character field could store date 
information as six characters, MM-DD-YY: 


12-22-55 


To print dates created in character fields in 
sorted order, you could sort by year, then month, 
then day, using the following SORT command: 


sort by purchdate[7,8], 
purchdate[1,2], 
purchdate[4,5] 
end 


The bracketed elements refer to the positions 
of characters in the field. 
This subscripting of 
the PURCHDATE field will cause the records to be 
sorted by the year, then the month, then the day, 
which will result in a chronologically sorted order- 
ing. 


This type of field subscripting. can be used 
with the SORT command on any character type field. 


You can also use sUbscripts to refer to part of 
a character field, in order to group records accord- 
ing to that subpart. 
For example, 


before (or after) group of purchdate[7,8] 
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IV.G. 
Using the UNIX or MS-DOS Opersting 
System Shell 


The OUTPUT command of ACE can be used to write 
an ACE report to an operating system file. 
One or 
more operating system utilities can then be used on 
the output. 


For example, a typical mailing list application 
might require printing onto a mailing label stock 
that has 8 labels down and three labels across. 
The 
UNIX program "pr" could be used to format the out- 
put. 


Another example of combining the UNIX or MS-DOS 
operating system with ACE would be "shell" programs 
to run the report. 
For example, if a report is to 
be parameterized with an ite. name, it would be nice 
to supply the user with a shell script that prompts 
for the parameter. 
The report for the item "File" 
would be as follows: 


~ itemrep File 


oname 


Hart, W. 
Court, S. 
English, D. 


item 


File 
File 
File 


quantity 


3 
5 
1 


An executable UNIX shell script could be used 
to issue a reminder if a parameter is not given. 


~ cat itemrep 
test "$1" • "" && echo Item parameter needed! 
&& exit 
acego -q itemrep1 $1 


This program runs the ACE report if a parameter 
is provided, or reminds the user that input is need- 
ed if no parameter is provided. 


A text-formatting utility, such as "nroff" or 
"TeX" can perform right-margin justification, page 
numbering, and many other services. 
ACE programs 
can work with files that include the special charac- 
ter sequences expected by these programs. 
ACE re- 
ports can therefore be immediately sent to a text- 
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formatting program for further processing. 


A command line that could be used to have ACE 
produce a report and then run it through the "nroff" 
text formatter is shown below: 


acego -q bulkmail I nroff -s1 > /dev/lp 


In this case, the program bulkmail could be an 
ACE program which reads names and addresses out of a 
database and prints form letters to the line 
printer. 
The -8 flag can be used on the "nroff" 
command line to stop the printer, in order to put 1n 
new paper or envelopes. 
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IV.H. 
Causing the OUtput To Pause Molll!ntarily 


The PAUSE statement ot ACE may be used to pause 
between groups of fields that are being printed on 
the screen or on a hard-copy terminal. 
With a 
hard-copy terminal 
(PAUSE only works on the standard 
output) you could print mailing addresses directly 
onto the envelopes and use the PAUSE statement 
between each label, so that a new envelope could be 
put into the printer. 


The PAUSE statement functions only when the re- 
port is printed to the standard output. 
If an OUT- 
PUT command is used to send the 
~eport to another 
device (a line printer) or to an operating system 
file, the PAUSE statement will have no etfect. 


The PAUSE statement is most otten used when the 
output is being printed to 
8 video terminal. 
It the 
data being printed using the ON EVERY RECORD command 
fits on the 24 lines on the screen, then the PAUSE 
statement might be used at the end ot the ON EVERY 
RECORD clause to achieve a "paging" effect. 


When the PAUSE statement is used in an ACE pro- 
gram, a quoted string may be supplied using the fol- 
lowing syntax. 


pause "ACE displays this message." 


When the PAUSE statement executes, it displays 
the prompt string that 1s supplied in this way. 
Press RETURN to continue printing. 


It no quoted string is supplied, printing will 
pause without any message. 
Again, press RETURN to 
continue printing. 
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IV.I. 
Printing Without Trailing Blanks 


The PRINT statement will always print fields 
and quoted strings as a fixed number of characters. 
This makes it easy for ACE programmers to look at 
the program and verify by calculation that the data 
in the columns will line up under the column 
headers, or whatever positioning is desired. 


However, fixed-length fields are not always 


suitable for printing mailing addresses. 
Suppose an 


add~ess has the following form: 


Firstname Middleinitial Lastname 
Street Address 
City, State 
Zip 


For a given record, a value for the field 


Middleiniti~l might not actually exist, or the 
street address might be more than one line. 
There 
might also be a country field at the end of the ad- 
dress. 


The WITHOUT TRAILING BLANKS option is very use- 
ful for printing fields such as FIRSTNAME and CITY, 
where it is desirable to trim off any trailing 
blanks. 


IF-THEN-ELSE statements can also be used to 
help print a properly structured address regardless 
of individual variations in records. 


The" utility of the WITHOUT TRAILING BLANKS op- 
tion is demonstrated by the two contrasting examples 
below. 
Consider the following schema. 


field firstname 
type character length 20 
field middle initial type character length 1 
field lastname 
type character length 20 


When these fields are printed using the regular 
PRINT statement, the results are as follows. 
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print firstname, 
ft 
ft, middleinitial, 
ft. 


lastname 


ft, 


John 
J. 
Smith 


When the fields are printed using the PRINT 


statement with the WITHOUT TRAILING BLANKS option, 
the results are as follows. 


print firstname without trailing blanks, 


W ", middleinitial,". 
ft, lastname 


John J. 
Smith 


A shorthand for the phrase WITHOUT TRAILING 
BLANKS is CLIPPED, as shown below. 
The above PRINT 
statement could also have been written as shown 
below. 


print tirstname clipped, 1 space, middleinitial, 


ft. 
ft, lastname 


However, if there is no entry in the 
middleinitlal field, the above PRINT statements will 
still print a period. 
Printing can be further con- 
trolled with the addition of an IF-THEN-ELSE state- 
ment. 
The following example also demonstrates the 
use at the semicolon (;) to suppress a 11nefeed. 


print firstname clipped, 1 space; 
it middleinitial <> " " then 
print middleinitial, ".", 1 space; 
print lastname 


The IF-THEN statement correctly handles the case of 
no entry in the aiddleinltlal field. 
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IV.J. 
Skipping to the Top of the Page 


A page break may be used to improve the appear- 
ance of sorted reports. 
If a long orders file were 
being printed out sorted by item, it might take 
several pages to print out a group of records for a 
particular item. 
The appearance of the output could 
be improved by having each group of items begin on a 
new page. 


The SKIP TO TOP OF PAGE 
st~tement could be used 
inside an AFTER GROUP OF clause to cause a page 
break after a group: 


after group of item 
skip to top of page 


Of course, other statements may be mixed with 
this statement in the AFTER GROUP OF clause. 


SKIP TO TOP OF PAGE may be used in clauses oth- 
er than AFTER GROUP OF clauses, but some restric- 
tions apply. 
The SKIP TO TOP OF PAGE statement is 
not allowed in either the PAGE HEADER clause or the 
PAGE TRAILER clause. 
(In PAGE HEADER clauses, it 
would cause an unending sequence of page headers. 
After the PAGE TRAILER clause, the skip to the top 
of the next page is automatic.) 
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IV.K. 
Printing ASCII Special Cbaracters 


ACE reports can include requests to print out 
special characters from the ASCII character set. 
Special characters (or any ASCII character) are 
·identified by the keyword ASCII and their number in 
the character set, for example, 


ascii 7 


ASCII 7 is the "bell" character on most terminals. 
The ASCII keyword can be used only within the FORMAT 
block. 
The statement 


print ascii 7 


should cause your terminal to emit its bell or beep 
sound. 


Special characters or a sequence of special 
characters may be given a user-defined name in the 
DEFINE block, assigned a value with a LET statement 
in the FORMAT block, and then printed With PRINT 
(also in the FORMAT block). 
For example, if you 
know the sequence of characters that causes your 
hard copy terminal to switch to a red ribbon during 
printing, you can use the following: 


define variable red output type character length 3 
define variable color_off type character length 3 
end 


format 
let red output = ascii 9, ascii 11, a$cii 1 
let color_otf • ascii 9, ascii 11, ascli 0 
. 
print red output, 
"Your bil! was due weeks ago!!!!", 
color_ott 


end 
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V. 
Complete Definition of the ACE Language 


V.A. 
General Syntax for ACE Programs 


V.A.1. 
Free Format Language 


ACE has certain rules that must be followed 
when you create reports. 
For example, numbers must 
be typed using a particular form. 
The characters 
"-3.14" form a legal n"mber. 
"3.14-" and "3.14D" 
are not legal numbers. 


ACE is a "free format" language. 
There are no 
rules regarding how many lines commands and keywords 
must occupy. 
However, there is a specific order in 
which the commands must appear. 
The commands in 
this section are presented in the required order. 
Other than order, the user may use whatever conven- 
tions are desired to format the program so that it 
is as readable as possible. 


You can give ACE commands in either upper- or 
lowercase unless the characters are inside quotation 
marks. 
Characters between quotation marks will be 
printed exactly as you type them, with upper- or 
lowercase preserved. 


Variable names, field names, file names, and 
reserved words are all made into lowercase by the 
compiler when the program is executed. 
This means 
that user-defined variable names that differ only in 
case (e.g., month, Month) will not be considered 
unique. 
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V.A.2. 
Coaments 


Any sentences you 'put inside of curly brackets 
({}) will be considered to be comments. 
Comments 
are for your own use or that of other users. 
They 
explain or remark on lines in the ACE program. 
Com- 
ments will be ignored when the ACEPREP compiler 
translates the source code file. 


Comments may span more than one line. 
The ex- 
ample below shows ACE comments: 


~ cat comments 
database stores end 


define 
param[1] thisitem 
type character 
length 20 
end 


{This parameter will be} 
{used to hold a selected item.} 


read 
orders 
where item = thisitem 
end 


Notice that the param[1] 
par~meter was used above, 
and assigned to the variable "thisitem". 
Only the 
selected records will now be availabfe for 
processing. 
} 


format every record end 
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V.A.'. 
Humbers 


Numbers in ACE programs mayor may not be a 
decimal. 
To set the left margin to 15, instead of 
the default of 5, the expression involving the 
number 15 expects an integer (a number without a 
decimal portion). 
If a decimal number occurs where 
it is not expected, the decimal part will be ig- 
nored. 


However, you can use both integers and "real" 


numbePs (decimals) in calculations. 
Since division 
with integers results in a quotient that is rounded 
off to the nearest whole number, division using real 
numbers can give you more accurate results. 


Both integers and real numbers may 
tive or negative sign in front of them. 
signs or commas are not allowed, except 
USING clauses. 


have a posi- 
Dollar 
in the PRINT 


Real numbers may also use "exponential nota- 
tion." For example, the number 345,000,000,000,000 
might be more conveniently expressed as 345e12. 
This translates to 345 times 10 to the twelfth 
power. 
There may not be any blanks between the ele- 
ments of this number. 
In other words, the 345e12 
must all be typed consecutively. 


Both the base number and the power may have an 
optional positive or negative sign. 
Numbers in ex- 
ponential notation may also be decimals. 
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V.A.4. 
Database, File, Field, and Variable Na-es 


The database name, the file names and field 


nam~s that are used in the ACE program should follow 
the same rules as those specified for DBBUILD. 


Variable names may be as long as 50 characters. 
All of the characters in the variable name are used 
when the program is trying to determine if a given 
variable name is unique. 


The variable name may contain upper- and lower- 
case characters, but case is not significant in com- 
parisons. 
As mentioned, a variable name that 
differs from another variable name only in the case 
ot letters will not be considered unique. 


Only alphabetic and numeric characters may be 
used when constructing variable names, in addition 
to the special character" "(underscore). 
Variable 
names must begin with an aTphabetlc character. 
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V.B. 
The DATABASE Command 


The DATABASE command specifies the name of the 
database from which the report is to be written. 
An 
example is offered below. 
The DATABASE command is 
required, and is usually the first line of the ACE 
program file. 


database stores end 
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V.C. 
The DEFINE Command 


The DEFINE command is used to define variables 
or parameters that are used in the ACE program, as 
well as C functions that can be linked in when the 
program is executed. 


Below are three examples of the DEFINE command. 


define 
variable counter type integer 
variable specialtotal type double 
variable selectionvalue type character length 10 
end 


The first variable is declared to be an in- 
teger. 
Integers are initially set to 0, and are 
subsequently assigned values with LET statements. 
Any fractional part of the value of an expression 
assigned to an integer variable is not displayed 
(integers show only whole numbers). 


The next variable is declared to be a double 
precision floating point number. 
A variable field 
of type double can show decimals without loss of the 
fractional part. 


The last variable above is a character vari- 
able, declared to be of length 10. 
Character vari- 
ables are usually used for gathering character 
strings from the user interactively, through the use 
of the INPUT command. 


Up to 100 variables, parameters, and/or func- 
tions may be defined in anyone ACE 
prog~am. 
If variables are defined as numbered parameter, 
they may be initialized with values passed to the 
ACEGO program, at run-time, from the operating 
system's command line. 
The DEFINE statement below 
would permit three variables to be initialized on 
the command line. 


define 
param[1] salary type double 
param[2] daysworked type integer 
param[3] empname type character length 20 
end 
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These parameter variables are exactly like the 
regular variables, except they are initialized from 
arguments on the command line. 
The variable associ- 
ated with param[1] will contain the first command 
line argument following the name of the report. 
For 


example, 


acego rep6 45000 201 Jamison 


would set salary to "45000", days¥orked to "201", 
and e.pnaIRe to "Jamison". 


Variables for parameters may be defined togeth- 
er with regular variables. 
There may be up to 100 
parameter variables, user variables, and function 
definitions within an ACE report. 
If a program uses 
parameter variables and the user of the 
ACE program 
does not provide them on the command line at run- 
time, then the 
ACE program will print a fatal error 


message and its execution will terminate. 


The linking of ACEGO to custom-written C func- 
tions is discussed further in Section VII of this 
chapter. 
However, the syntax for defining a func- 
tion is shown below for completeness. 


define function predict end 


This DEFINE statement alerts the ACEPREP compiler 
that a function named predict may be called in the 
FORMAT section with the "call [functionname]" state- 
ment. 
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V.D. 
The INPUT Co.-and 


The INPUT command with the PROMPT 'FOR clause 
initializes variables defined in the DEFINE state- 
ment by prompting the user for the initial value. 
If there are any INPUT commands, they must precede 
the READ command. 
The syntax for a typical INPUT 
command is shown below. 


input 
prompt for selectionvalue using 
"Please select the item for the report > " 
end 


When the report begins running, the prompt 
string used in the prompt statement will be printed. 
The user's response becomes the initial value of the 
variable. 


You cannot prompt for database file names or 
output file names using the INPUT command or the 
.PROMPT FOR clause. 
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V.E. 
The OUTPUT COllllDand 


There are several default values that are as- 
sumed by ACE for page dimensions•. The top and bot- 
tom margins are 3 lines each. 
The left 
ma~gin is 5 
spaces (the report begins in column 6). 
The page 
length is assumed to be 66 lines, and the page width 
is assumed to be 132 characters (typical line 
printer paper). 
Finally, the report will be 
displayed on the terminal from which the report is 
run. 


You can change these defaults with the OUTPUT 
command. 
If there are any OUTPUT commands, they 
must precede the READ command. 
Here is an OUTPUT 
command that changes all of the defaults. 


output 
page length 24 
{A typical CRT terminal size} 
right margin 80 {Also typical of a CRT} 
left margin 0 
top margin 2 
bottom margin 1 
report to "screenfile" 
end 


NOTE: Setting a right margin has no effect if 
there is a PRINT statement in the FORMAT section, or 
if a conventional FORMAT command is used containing 
ON EVERY RECORD or other similar clauses. 
If you use a FORMAT EVERY RECORD statement, 
each field appears on a new line if the number of 
characters per record would exceed the specified 
right margin. 


The REPORT TO statement can cause ACE to write 


the report to an operating system file. 
The file 
can then be viewed with a program that "pages" 
through a file, or with an editor. 
Enclose the file 
name in quotation marks. 
Under UNIX, the file name 
can also be the name of a device, such as /dev!lp. 
If a printer spooling program has been in- 
stalled, you can also send output directly to a 
printer. 
Under UNIX, use the following syntax: 
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output 
report to printer 


end 


Under MS-DOS, use the following syntax: 


output 
report to "lpt1" 
end 


The REPORT TO option can be mixed with other out- 


put options. 
If the REPORT TO option is used, only 
the report will go to the printer or file as speci- 
fied in the command. 


When a report is sent to a file or to the 
printer, the messages printed by ACEGO during the 
execution of a program will still be printed to the 
terminal, unless the -q flag is used. 


However, you can pipe output to a printing pro- 
gram (such as the UNIX "lpr" utility) as well as us- 
ing the REPORT TO 
PRI~rER option. 
Both methods 


separate the output of 
ACE~O into two streams, one 


for the printer, and one for the standard output 
(the terminal, unless redirected). 
ACEGO will print 
messages regarding fatal errors to standard error; 
these messages will print at the terminal, even if 
standard output is redirected. 


The UNIX command that pipes ACE output to the 
"lpr" program is: 


~ acego -q ordersrep I lpr 


Also under UNIX, the OUTPUT option that senqs 


the report to a file can be modified to pipe the're- 
port to the standard input of any program, even a 
program that writes to a tape or other device. 
The 
syntax is: 


output 


report to pipe "nroff > finalresult" 
end 
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V. F. 
The READ COlllJll8l1d 


The READ command has the same syntax as INFORM- 
ER READ commands. 
ACE requires at least one READ 
command, but allows any number. 
The temporary file 
that is created by the last READ command is the one 
that is used as input to the FORMAT command. 


As mentioned, optimized reading of a file is 
accomplished with a single READ command when no tem- 
porary file is created, as follows: 


read orders end 


The WHERE and JOINING clauses may be used in 
optimized READ statements. 
The only restriction to 
the optimized READ is that it must be the last READ 
statement 1n the report. 
An optimized READ lacks 
the phrase INTO X, where X is any temporary database 
file. 


Since an optimized READ does not create a tem- 
porary file, it does not require any extra disk 
space for a work area, and it may even execute more 
quickly than a READ statement using temporary files. 
(See also Section IV.E. of this chapter.) 


The READ command's syntax is shown on the fol- 


lowing page. 
For more information about the READ 
command, see the INFORMER chapter. 


.. 
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The detailed syntax of the READ cGmmand is as 
follows: 


) 
READ [INTO X] fieldlist {WHEREclause 
} END 
{JOININGclause } 


where the two choices in curly brackets are 
optional, and where 


fleldlist • 
one or more field names or file 
names separated by commas, 
blanks, or the word "and" 


JOININGclause • 
the keyword JOINING followed by 
one or more field • field 
expressions 


VHEREclause • 
the keyword WHERE followed by a 
logical-expression 


logical-expression • field relop constant 


or 
logical-expression 
logop 
logical-expression 


where a relop is one of the following symbols 


• 
<> 
< 
> 
<. 


and a logop is one of the logical operators 
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The SORT command can be used to specify a sort- 
ed ordering for the records before they are pro- 
cessed by the FORMAT section. 
The syntax for a SORT 
command is shown below. 


sort by item quantity end 


In this example. there are two levels in the 
hierarchy of the sort. 
All of the records will be 
sorted by ite.. 
If there are several records with 
the same value for item. then these records will be 
sorted by quantity within the group of ite. records. 


The modifiers ASCENDING or DESCENDING may be 
attached to each of the fields in the field list. 
ASCENDING is the default. 
Each field in the list 
may be modified separately. 


The following SORT command sorts by item in 
descending order and quantity in ascending order. 


sort by item descending quantity end 


Character fields maybe subscripted for sorts 
using the following syntax. 


sort by trackingcode[4.5] warehouse end 


In this example. the tracklngcode field is 
sorted by its fourth and fifth characters. 
It is 
often desirable to be able to sort records by sub- 
fields, in order to get a certain grouping or order-. 
Ing. 
You may sort by as many as eight fields and 
120 characters. 
In other words, you can sort by 
only three fields if each is 40 bytes long. 


A full description of the syntax of the SORT 
command follows. 
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SORT BY attlist END 
attlist = att[ASCENDINGIDESCENDING] 
orattlist separator att 


att = attname 
or attname[n,m] 
{(where nand m 
{(and m > n 
> O)} 
) } 


{separator = a comma, the word AND or one 
or more blanks or new lines} 
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V.H. 
The FORMAT Collllland 


The FORMAT command is composed of combinations 
of up to seven clauses: 


• 
FIRST PAGE HEADER 


• 
PAGE HEADER 


• 
PAGE TRAILER 


• 
ON EVERY RECORD 


• 
BEFORE GROUP OF 


• 
AFTER GROUP OF 


• 
ON LAST RECORD 
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V.B.1. 
!he FIRST PAGE HEADER Clause 


You may want to include 
diffe~ent information 
in the header on the first page than on subsequent 
pages. 
The text you specify with the FIRST PAGE 
HEADER clause appears immediately after the top mar- 
gin of the first page of the report. 
It does not 
appear on subsequent pages. 


You can specify column headings for your report 
in both the FIRST PAGE HEADER and the PAGE HEADER 
clause. 


Certain options that are legal in the other 
parts of the FORMAT section are not permitted in the 
FIRST PAGE HEADER clause: 
The SKIP TO TOP OF PAGE 


command is illegal. 
And IF-THEN-ELSE statements are 
not allowed unless the number of lines printed out 
by the IF part is identical to that printed out by 
the ELSE part. 
Finally, you are not permitted to 
read in text from an external file in the FIRST PAGE 
HEADER clause. 
. 
If there is a PAGE HEADER clause but no FIRST 
PAGE HEADER clause, all pages will have the same 
header. 
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V.H.2. 
The PAGE HEADER Clause 


Text you specify with the PAGE HEADER clause 
appears immediately beneath the top margin on every 
page of the report, except that a FIRST PAGE HEADER 
clause can cause a different text to appear on the 
first page. 


You can use the PAGENO keyword to cause a page 
number to be printed in the page header. 
For exam- 
ple: 


page header 
print pageno 


The same restrictions on not using SKIP TO TOP 
OF PAGE, etc. apply to the PAGE HEADER clause as to 
the FIRST PAGE HEADER clause. 
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V.B.,. 
The OR EVERY RECORD Clause 


The ON EVERY RECORD clause determines the ap- 
pearance of the detail lines of the report. 
ON 
EVERY RECORD is usually used to print part or all of 
the records that were qualified by the last READ 
statement. 
However, 
ON EVERY RECORD can also be 
used to obtain intermediate results that can be 
printed later. 
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w.n.4. 
The BEFORE GROUP OF and AFTER GROUP OF 
Clauses 


The SORT command may contain up to eight fields 
in a hierarchical sort. 
Each one of these sorted 
orderings imposes a grouping on the records, which 
is also hierarchical. 
The BEFORE GROUP OF and AFTER 
GROUP OF clauses control print statements to be exe- 
cuted either before or after the group changes. 


The BEFORE and AFTER GROUP OF clauses may also 
be nested. 
It is not necessary that this nesting 
follow the order in which fields are nested for the 
SORT command, but the SORT nesting order will always 
be followed when the report is printed out. 


The example below shows BEFORE GROUP OF clauses 
nested in the same order as the fields in the sort 
list. 


sort by state, city end 
. 
format 
before group of state 
. 
before group of city 


end 


• .. .8. 
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The example uses the BEFORE GROUP OF clause. 
You can use both BEFORE GROUP OF and AFTER GROUP OF 
clauses, as shown below. 


sort by city, state end 
. 
format 
before group of state 
. 
after group of state 


before group of city 


after group of city 


end 


The statements in a BEFORE GROUP OF clause ap- 
ply to records from the group of records that is 
about to be processed. 
The statements in an AFTER 
GROUP OF clause apply to records from the group of 
records that was most recently processed. 


When the report begins printing, all of the BE- 
FORE GROUP OF statements are triggered before the 
first ON EVERY RECORD 
sequ~nce of statements is exe- 
cuted. 
The BEFORE GROUP OF statements will be exe- 
cuted in the order that fields are listed in the 
SORT command. 


When a control break or change of value (hence, 
change of group) occurs for any field in a SORT 
hierarchy, all of the fields nested within that 
field experience a change of group as well. 


When the last record is processed, all of the 
AFTER GROUP OF statements will be executed before 
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the ON LAST RECORD clause. 


Group aggregates may be used only in the AFTER 
GROUP OF clauses because the values are calculated 
by ACE while the records in the group are processed. 


If the SORT command contained a sUbscripted 
field, control breaking may be performed on the same 
subscripted field. 


In order to get a different page header for 
each group, you must use the SKIP TO TOP OF PAGE 
statement in the BEFORE GROUP OF clause. 
This will 
put the correct header on each group, but it will 
also generate a blank page at the beginning of the 
report. 
Moreover, page numbers displayed by the 
PAGENO command will be off by one. 
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V.B.5. 
The ON LAST RECORD Clause 


After all of the ON EVERY RECORD and AFTER 
GROUP OF clause printing is done and the last record 
has been processed, then the ON LAST RECORD printing 
will occur. 


This clause is very useful for printing totals. 
Some reports do nothing but perform some calcula- 
tions and then print the results with the ON LAST 
RECORD clause. 
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V.H.6. 
The PAGE TRAILER Clause 


Text you specify with the PAGE TRAILER clause 
will be placed at the bottom of each page, just 
above the bottom margin. 
The ACEGO program will not 
let printing intrude on the space reserved for the 
page trailer. 
The size of the space reserved 
depends on the total number of print statements and 
skipped lines that are coded in the statements con- 
ditioned on the PAGE TRAILER clause. 


Therefore, it is important that if you use an 
IF-THEN-ELSE statement in a PAGE HEADER or PAGE 
TRAILER clause, the IF part must permit the same 
number of lines as the ELSE part. 
If this is not 
the case, ACEPREP notifies the user of this condi- 
tion. 
For the same reason, you must use the semi- 
colon to suppress the newline in PRINT statements 
used in FOR or WHILE loops in PAGE HEADER or PAGE 
TRAILER clauses. 
If you want page numbers at the bottom of the 
page, use a PRINT PAGENO statement in the PAGE 
TRAILER clause. 
For example: 


page trailer 
print 20 spaces, pageno using "page ###" 


will print at the bottom of the first page: 


page 
1 


The same restrictions on skipping to top of 
page and reading in an external file apply to the 
PAGE TRAILER clause as to the PAGE HEADER and FIRST 
PAGE HEADER clauses. 
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V.I. 
The Statements 


V.I.1. 
The Simple PRINT Statement 


The PRINT command can be used to print quoted 
strings of characters, character fields, arithmetic 
fields, expressions (which may include aggregates), 
or any of the special print items, such as DATE or 
TIME. 
This simple print statement prints the con- 
tents of the item field: 


print item 


If "Work Bench" is the value of the item field, 
the output is: 


Work Bench 


If the item field is defined to be 15 charac- 
ters long, then 15 characters are actually printed. 
There are five blanks to the right of the word 
"Bench". 
Consider the two PRINT statements below. 


print item, quantity 
print quantity, item 


If the item field contained "Work Bench" and 
the quantity field contained the arithmetic value 5, 
the output for these two statements would be: 


Work Bench 
5 
5Work Bench 


The first line of output shows the item field 
being.printed with its full 15 characters, followed 
by the quantity field which is printed in the de- 
fault format for integers. 
Integers printed without 
a modifying USING phrase are right-justified in a 
field of five characters, blank-padded to the left. 
The effect of this can be seen in the second line of 
output. 


The default format for fields of type double is 
14 spaces: 11 spaces for the integer portion, 1 
space for the decimal point, and 2 spaces for the 
fractional part. 
The USING phrase of the PRINT 
statement is usually used to format integers, dou- 
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bles, and results of expressions. 
The result of any 
expression (anything arithmetic other than a field) 
is put into a double-sized field, by default. 


Blanks can be printed to separate print fields 
in the lines of the report by two methods, both of 
which are shown below. 


print oname," 
", 
item, 2 spaces, 
quantity 


Above, blanks are printed first as explicit 
blanks in a quoted string and then using the SPACES 
phrase. 


A PRINT statement automatically prints out 
everything on one full line on the report, even 
though a single PRINT statement may take up more 
than one line in the program, as above. 


If a PRINT statement is terminated with a semi- 
colon, then the printing in the report stays on the 
line that is being printed, and the next PRINT 
statement continues printing on the same line. 
This 
is useful when a BEFORE GROUP, OF clause is printing 
some heading information, and the first line of de- 
tail printing in the group needs to be printed on 
the same line. 
A semicolon at the end of any PRINT 
statement will suppress the newline and cause print- 
ing to continue on the same line. 


Functions such as DATE and TIME can be printed 
from any clause. 
The formats of the date and time 
that are printed are shown in Section IV.A. 


The remaining items commonly found in PRINT 
statements are variables, including parameter vari- 
ables, as discussed in Section IV.B. 
The default 
print format for these items will be according to 
their declared type. 


The ability to suppress the printing of blanks 
at the end of a field has already been discussed 
(Section IV.I). 
The syntax for this feature is: 
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print quantity, " ", 
item clipped, 
" items are currently on order." 


This produces the following output: 


5 Work Sench items are currently on order. 


You can control exactly where information 
prints with the COLUMN keyword. 
For example, to 
align two column 
headings,-y~u could use: 


print column 43, "First Name", column 56, "Last Name" 


ACE adds each column number to the left margin you 
set in the OUTPUT section or to the default left 
margin. 


You can use the NEED N LINES expression to keep 
information together on a page. 
Simply enter "need 
n lines" on a line of its own, when "n" specifies 
the number of lines of text you want to keep togeth- 
er. 
NEED N.LINES can be used in any clause where a 
PRINT statement can be used. 
For example: 


before group of last name 
need 5 lines 
- 
print last name 
print address 
print address2 
print phone 
print zip 


In the above example, for each group the NEED N 
LINES expression causes ACE to execute the PRINT 
statements in the "SEFORE GROUP OF clause only if at 
least five lines remain on the page. 
Otherwise, ACE 
starts a new page. 
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V.I.2. 
Printing Operating System Files 


The PRINT statement can be used to print the 
text of any operating system file. 
This facility is 
very useful when printing a large body of text, such 
as a form letter. 
The file may exist in the current 
directory, or in another operating system directory. 
Under UNIX, you may specify a full pathname for the 
file to be printed. 


The statement should read as follows. 


print file "filename" 


This statement cannot be used in PAGE HEADER, 
FIRST PAGE HEADER, or PAGE TRAILER clauses. 


INFORMIX 


ACE Relational Report Writer 


V.I.'. 
Printing Numeric Fields and Expressions 


The PRINT USING statement has appeared briefly 
in some of the examples. 
The simple case that has 
been shown is to print a field using a 
"mas~" to 
format it. 


In the example below, the balance field is 
printed using a format string that would allow up to 
$9,999,999.99 to be formatted correctly. 


print "The current balance is ", 
balance using "$#,###,##&.&&" 


The results of executing this with the value 
23,485.23 would be as follows. 


... 


The current balance is $ 
23,485.23 


In this example, the dollar sign was "fixed" in 
a particular position. 
If dollar signs were used 
instead of the "#" fill character, the dollar sign 
would "float" with the size of the number. 


Also, a mix of the "#" and "&" fill characters 
was used. 
The "#" fill character will provide for 
blank-filling unused character positions, whereas 
the "&" character will provide for filling with zero 
(0). 
This format ensures that even if the number 
were zero, the positions to the right of the decimal 
point will be filled with zeros, not blanks. 
For 
example: 


$ 
0.00 


The format string can consist of any combina- 
tion of the special formatting characters < * & # , 
• 
( 
) 
- 
+ and $. 
These characters can be classified 
as follows: 


fill character indicators 
literal characters 
sign characters 
dollar sign character 


* & # < 
, . 
- 
+ 
( 
) 
$ 
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justify numbers. 
As has been seen, the "#" charac- 
ter is used for blank-filling, the "&" character for 
filling with zeros, and the "*" character for star- 
filling, which is useful when printing checks. 


The comma is a literal character that will be 
printed if there are numbers around it in the final 
printed field. 
Otherwise, it will take on the 
characteristics of the fill characters 
a~ound it. 


The decimal point may only be used once. 
It 
will always print. 


The plus and minus sign may float or be fixed, 
just as the dollar sign character. 
The floating 
characteristic of these characters will be demon- 
strated through numerous examples below. 


Finally, the parentheses may be used in the ac- 
counting sense, to indicate a negative number. 
The 
parentheses can also be made to float. 


All of the above rules also hold true for USING 
clauses that are part of LET statements. 


The examples below should show all of the ways 
that the USING characters can be combined and the 
results of such combinations. 
In the examples 
below, sometimes the character "b" is used to em- 
phasize the presence of an explicit blank. 
The 
character "b" is not printed. 
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Format String 
Numeric Value 
Formatted Result 
------------- 
------------- 
---------------- 
"#HHHN" 
0 
bbbbO 
"&&&&&" 
0 
00000 
"$$$$$" 
0 
bbb$O 
"*****" 
0 
****0 
"««(" 
0 
Obbbb 
"##,HU" 
12345 
12,345 
"HH,#HH" 
1234 
b1,234 
"HH,###" 
123 
bbb123 
"HH,HHH" 
12 
bbbb12 
"H#,HH#" 
1 
bbbbb1 
. "H#, ###" 
-1 
bbbbb1 
"#H,N##" 
0 
bbbbbO 


"&&,&&&" 
12345 
12,345 
"&&,&&&" 
1234 
01,234 
"&&,&&&" 
123 
000123 
"&&,&&&" 
12 
000012 
"&&,&&&" 
1 
000001 
"&&,&&&" 
0 
000000 


"$$,$$$" 
12345 
****** 
(overflow) 
"$$,$$$" 
1234 
$1,234 
"$$,$$$" 
123 
bb$123 
"$$,$$$" 
12 
bbb$12 
"$$,$$$" 
1 
bbbb$1 
"$$,$$$" 
0 
bbbb$O 


"**,***" 
12345 
12,345 
"** ***" 
1234 
*1,234 
, 
"** ***" 
123 
***123 
, 
"**,***" 
12 
****12 
"** ***" 
1 
*****1 
, 
"** ***" 
0 
*****0 
, 


92 
INFORMIX 


ACE Relational Report Writer 


Format String 
Numeric Value 
Formatted Result 
------------- 
------------- 
---------------- 
"##,###.##" 
12345.67 
12,345.67 


"##,###.##" 
1234.56 
b1,234.56 


,,##,###.##" 
123.45 
bbb123.45 
"##,###.##,, 
12.34 
bbbb12.34 
,,##.###.##" 
1.23 
bbbbb1.23 


"##.###.##" 
0.12 
bbbbbb.12 
"##,H##.H#" 
0.01 
bbbbbO.01 


,,##,###.##" 
-0.01 
bbbbbO.01 


,,##,###.##" 
0.00 
bbbbbO.OO 


"&&,&&&.&&" 
12345.67 
12,345.67 
"&&,&&&.&&" 
1234.56 
01,234.56 
"&&,&&&.&&" 
123.45 
000123.45 
"&&,&&&.&&" 
0.01 
000000.01 


"$$,$$$.$$" 
12345.67 
********* 
(overflow) 
"$$,$$$.$$" 
1234.56 
$1,234.56 
"$$,$$$.##" 
0.00 
$0.00 
"$$,$$$.##" 
1234.00 
$1,234.00 
"$$,$$$.&&" 
0.00 
$0.00 
"$$,$$$.&&" 
1234.00 
$1,234.00 


"-#N,###.##" 
-12345.67 
-12,345.67 
"-##,###.##" 
-1234.56 
- 1,234.56 
"-##.###.H#" 
-123.45 
123.45 
"-H#,###.##" 
-12.34 
12.34 
"--#,###.##" 
-12.34 
12.34 
"---,###.##" 
-12.34 
12.34 
-"---,-##.##" 
-12.34 
-12.34 
"---,_-#.##" 
-1.00 
-1.00 


"-##,###.##" 
12345.67 
12,345.67 


"-11#,###.##" 
1234.56 
1,234.56 


"-##,###.##" 
123.45 
123.45 
"-##,###.##" 
12.34 
12.34 
"--#,###.U" 
12.34 
12.34 
"---,###.##" 
12.34 
12.34 
"---,-##.H#" 
12.34 
12.34 
"---,---.##" 
1.00 
1.00 


It ___ , ___ • __ " 
-.01 
-0.01 
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Format String 
Numeric Value 
Formatted Result 
------------- 
------------- 
---------------- 
"---,---.&&" 
-.01 
-0.01 


"-$$$,$$$.8c8c" 
-12345.67 
-$12,345.67 


"-$$$,$$$.8c8c" 
-1234.56 
- $1,234.56 
"-$$$,$$$.&&" 
-123.45 
$123.45 
"--$$,$$$.&&" 
-12345.67 
-$12,345.67 


"--$$,$$$.8c8c" 
-1234.56 
-$1,234.56 
"--$$,$$$.&&" 
-123.45 
$123.45 


"--$$,$$$.8c8c" 
-12.34 
$12.34 


"--U,$$$.&&" 
~1.23 
$1.23 
"____ , __$.&&" 
-12345.67 
-$12,345.67 
"----,--$.&&" 
-1234.56 
-$1,234.56 
"____ , __$.&&" 
-123.45 
-$123.45 
"____ , __$.&&" 
-12.34 
-$12.34 
"____ , __$.&&" 
-1.23 
-$1.23 
"____ , __$.&&" 
-.12 
-$0.12 


"$***,***.&&" 
12345.67 
$*12,345.67 
"$***,***.&&" 
1234.56 
$**1,234.56 
"$***,***.&&" 
123.45 
$****123.45 
"$***,***.&&" 
12.34 
$*****12.34 
"$***,***.&&" 
1.23 
$******1.23 
"$***,***.&&" 
.12 
$******0.12 


"($U,$$$.&&)" 
-12345.67 
($12,345.67) 
"($U,$$$.&&)" 
-1234.56 
( $1,234.56) 


"($$$,$U.8c8c)" 
-123.45 
( 
$123.45) 
"«U,$$$.&&)" 
-12345.67 
($12,345.67) 
"«U,$$$.&&)" 
-1234.56 
($1,234.56) 
"«U,$$$.&&)" 
-123.45 
( 
$123.45) 
"«U,U$.&&)" 
-12.34 
( 
$12.34) 
"«$$,U$.&&)" 
-1.23 
( 
$1.23) 


"««,«$.8c8c)" 
-12345.67 
($12,345.67) 
"««,«$.&&)" 
-1234.56 
($1,234.56) 
" ( ( ( ( , ( (S. &&) " 
-123.45 
($123.45) 
" ( ( ( ( , ( ($. 8c8c) " 
-12.34 
($12.34) 
"««,«$. &&) " 
-1.23 
($1.23) 
"(«(,«$. 8c8c) " 
-.12 
($0.12) 
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Format Str ing 
Numeric Value 
Formatted Result 
------------- 
------------- 
---------------- 
"($$$,$$$.&&) 
12345.67 
$12,345.67 
"($$$,$$$.&&) 
1234.56 
$1,234.56 
"($$$,$$$.&&) 
123.45 
$123.45 
"({$$,$$$.&&) 
12345.67 
$12,345.67 
"({SS, $$$. &&) 
1234.56 
$1,234.56 
"({SS,$$$.&&) 
123.45 
$123.45 
" ({ $$ , $$$ •&&) 
12.34 
$12.34 
"«$$,$$$.&&) 
1.23 
$1.23 


"««,«$.&&)" 
12345.67 
$12,345.67 
"{{ «, «$.&&)" 
1234.56 
$1,234.56 
"{{ {( , ({ $. &&) " 
123.45 
$123.45 
"{ {{{, «$.&&)" 
12.34 
$12.34 
"{({{, ( ($. &&) " 
1.23 
$1.23 
"{{ {( , ( ($•&&) " 
.12 
$0.12 
"«<,«<" 
12345 
12,345 
"«<, «<" 
1234 
1,234 
"«<,«<" 
123 
123 
"«<, «<" 
12 
12 
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V.I.4. 
The Aggregates COUNT, MIN, MAX, PERCENT, 
TOTAL, 
and AVERAGE 


Aggregate operations will affect all records, 
unless you include a WHERE clause. 
You cannot nest 
aggregates within one another. 


The COUNT aggregate counts records. 
It is 
shown below in two ways: first printed, then used in 
an arithmetic expression. 


print "There were ", count using "HH###", 


n attendees at the" 
print "meeting this year." 
print 
print "We expect ", 2 * count using 
"#~###", 
"attendees at the-" 
print "meeting next year." 


When these statements execute, the results are 
as follows: 


There were 
25 attendees at the 
meeting this year. 


We expect 
50 attendees at the 
meeting next year. 


This usage assumes a selection of all the 
records in the report. 
READ or PRINT commands could 


be used to qualify records for the report, so that 
only some of those records would be counted. 
For 
example, the statement below. counts only those club 
members who have not yet paid their dues. 


print "There were"", 
count where balance> 0.0 
using "#,###", 
" members who still had dues to pay." 


This is an example of qualifying an aggregate 
with a WHERE clause. 


The PERCENT aggregate may be used just like the 
COUNT aggregate -- with or without a WHERE clause. 
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The GROUP COUNT and GROUP PERCENT limit the 
scope of operation to the group of records just pro- 
cessed; use them only 1n AFTER GROUP OF clauses. 
GROUP aggregates may be further qualified with a 
WHERE clause. 


The MIN and MAX aggregates find mini-mum and 
maximum values, respectively. 
You can also use 
GROUP MIN and GROUP MAX. 


The TOTAL and AVERAGE aggregates require an ex- 
pression. 
An expression can include arithmetic 
operations on one or -iItOt"e fields. 


Rrint "The total sales for the year are ", 
total of sales using "$$,$$$,$$&.&&", 
"." 


To calculate an inventory tax of ten dollars 
for each item in inventory, plus six percent of the 
item's value, use the following expression: 


print "The total tax paid on inventory is ", 
total of 10.00 
+ .06 * value 
using "$$,$$$,$$&.&&","." 


If the tax were ten dollars flat, plus six per- 
cent for each item, then the expression would need 
to change so that the ten dollars is not added for 
each 1tem. 


print "The total tax paid on inventory is ", 
10.00 + total of .06 * value 
using "$$,$$$,$$&.&&","." 


Still another way to express 
~his is as fol- 
lows: 


print "The total tax paid on inventory is ", 
(total of .06 * value) .+ 10.00 
using "$$,$$$,$$&.&&","." 


Parentheses can be used in expressions to 
clearly delineate what numbers are involved in what 
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exp~essions. 
Fo~ example, 


total of quantity 
whe~e quantity = 1 
+ 1 


would not 
p~int one plus the total of the quantity 


whe~e the quantity value is one. 
It would print the 
total of the quantity field 
whe~e the quantity was 


two (one plus one). 
Parentheses should be used to 


cla~ify the 
exp~ession: 


(total of quantity 
whe~e quantity = 1) 
+ 1 


The AVERAGE and GROUP AVERAGE 
agg~egates 
a~e 


identical to the TOTAL 
agg~egates. 
except the total 
is divided by the 
numbe~ of 
~eco~ds that 
we~e in- 
volved in the totaling. 
The 
exp~essions that can be 
used are the ·same. 
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V.1.5. 
The LET State.ent 


Variables that have been defined in the DEFINE 
command may be assigned values. 


let runningcount = runningcount 
+ 1 


The left side of the statement is any arithmet- 
ic variable, and the right side is an expression. 


When expressions are assigned to INTEGER type 
variables, any fractional part is lost. 


Fields and variables defined as type CHARACTER 
may be used in calculations, as long as they contain 
legally formatted numbers. 
If a character-to-number 
conversion error occurs during the running of a re- 
port because a number was not properly structured in 
a CHARACTER field or variable, 
ACEGO terminates with 
an error message. 
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V.1.6. 
The 1F-THEN-ELSE Statement 


The IF-THEN-ELSE statement is reviewed here. 
A 
simple IF statement is shown below. 


if (saleprice > average of saleprice) 
then 
begin 
print "Above average." 
end 


The PRINT statement between the BEGIN and the 
END keywords could have been a series of statements. 
In fact, any series of statements may be bracketed 
by BEGIN-END pairs to form a single "compound state- 
ment" that can be used wherever a simple statement 
can be used. 


An example that 
use~ an ELSE part is shown 
below. 
Note that the BEGIN and END bracketing 1s 
only required if there is more than one statement 
following a THEN or ELSE keyword. 


if (saleprice > average of saleprice) 
then 
print "Above average." 
else 
print "Below average." 


A maximum of 2; conditions are allowed in an IF 
statement. 
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An example demonstrating nested IF-THEN-ELSE 
statements is shown below. 
There is no limit on the 
number of levels of nesting of these statements. 


if (saleprice > average of saleprice) 
then 
begin 
if (saleprice > 1000000.00) 
then 
begin 
print "This is way above average price." 
end 
else 
begin 
print "Above average." 
end 
end 
else 
begin 
print "Below average." 
end 
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V.J. 
The Date Functions 


V.J.1 
The DAY, MONTH, and YEAR Functions 


ACE has three functions that you can use to ex- 
tract the day, month, and year from a date field or 
other expression. 
You can use the DAY, MONTH, and 
YEAR functions anywhere you would normally use an 
expression. 
The syntax is as follows: 


day(expression) 
month(expression) 
year(expression) 


where "expression" is the name of a database field 
or any other expression. 
The DAY, 
MONTH, and YEAR 
functions select the day, month, and year from any 
database field of type DATE, 
YDATE, or EDATE. 
If 
you use an expression which is not one of these 
types of database fields, 
ACE assumes the" format is 
that of the DATE type. 


'You might use these functions to limit the 
scope of a query with the READ command: 


read listings 
where month(date listed) > 2 
and year(date_1Isted) >= 82; 


This READ command selects records in which the 
date listed field contains a month between March and 
December and a year 1982 or later. 


The DAY, 
MONTH, and YEAR functions also enable 
you to sort a report by days, months, and years. 
An 
example follows. 
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database newsample end 


read into 
:It 


days 
= day(date listed), 
months = month{date listed), 
years 
= year(date listed), 
date listed 
- 
end 
- 


sort by years, months, days end 


format 
on every record 
print date_listed 
... 
after group of months 
print "Monthly totals: ", 


end 
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V.J.2 
The MOY Function 


The MDY function lets you convert three expres- 
sions into a date. 
You can use it anywhere you can 
use an expression. 
For example: 


read into x listings, new_date 
= mdy(12,1,84) 


creates a temporary field named new date and gives 
it the value 12/1/84 as a result of-the MDY func- 
tion. 


MDY will attempt to format any three numbers 
given to it as a date in standard MMDDYY format. 
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V.J.3 
T~ WEEKDAY Function 


The WEEKDAY function lets you determine the day 
of the week for a particular date. 


weekday(expression) 


returns an integer from 0 through 6, with 0 
corresponding to Sunday, 1 to Monday, 2 to Tuesday, 
etc. 


In practice, you might use the WEEKDAY function 
as follows: 
if (weekday(today) 
z 5) then 
print "Today is Friday." 
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V.J.4 
The DATE, EDATE, and YDATE 
Fu~~+'ions 


The DATE, EDATE, and YDATE functions allow you 
to convert the value of an expression to type DATE, 
EDATE, or YDATE, then store the value in a temporary 
variable. 
The syntax is: 


temp field 
= date(expression) 
temp-field 
= ydate(expression) 
temp:field 
= edate(expression) 


You might use these functions to convert data stored 
in one type of date field into another format for 
printing. 
For example, if date-posted is a YDATE 
field, you might print it in EDATE format like this: 


print edate(date-posted) 
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VI. 
Examples 


VI.A. 
Creating Forms - Personnel Review 


The following example demonstrates how salary 
review forms can be generated from a personnel data- 
base. 
In the sample output 
OA the next page, some 
of the fields in the form have already been filled 
in by the ACE program. 
Room has been left for other 
information to be supplied by each employee's super- 
visor. 
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SALARY REVIEW 


Name: Anderson, Marion A. 
Date Employed: 04/01/75 


Date of Last Review: 06/01/81 
Employee # : 1324 


Present Rate: $35,000.00 


Recommended New Rate: $38,500.00 


Date effective: 01/01/82 


Department: Inventory Control 


Position and Responsibilities: Inventory Mgr 


New Position and/or Responsibilities Recommended: 


Comments: 


Supervisor's Signature 


Personnel Manager's Signature 


Operation Manager's Signature 
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Two files were used to store the information 
used in this report. 
They are shown on the next 
page. 
The e.ployees file contains information for 


each employee. 
One of the items of information in 
this file is the employee's department number. 
How- 
ever, the salary review form should show the word 
"department" spelled out for clarity. 


The departments file contains information about 
the departments, including the department number and 
the name. 
A JOIN between the department number in 
the e.ployees file and the department number 1n the 
departments file will allow the department name to 
be associated With each of the employees, so that 
the ACE report program can print it on these salary 
review sheets. 


The ACE program that contains this JOIN and 
prints the salary review forms is shown after the 
schemas. 
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database company 


file employees 


{Personnel Information} 


field emp name 
field emp-number 
field emp-address1 
field emp-address2 
field emp-address3 
field emp-phone 
field emp:birth 


type character 
type integer 
type character 
type character 
type character 
type character 
type date 


length 25 
{ID number} 


length 25 
length 25 
length 25 
length 14 


{Business Information} 


field emp title 
type character 
length 25 
field emp-dept num 
type integer 
{dept number} 
field emp-hlre-date type date 
field emp-term-date 
type date 
field emp-Iast-review date 
type date 
field emp-salary effective date 
type date 
field emp-salary- 
type double 
{Per annum} 
field emp-status 
type character 
length 1 
{"e".employed 
"t"..terminated 
"l"=on leave 
"d"=disabled} 


field emp rating 
{"poor" 
"fa"ir"- 


end 


database company 


type character 
length 8 
"good" 
"superior"} 


file departments 


field dpt_dept_num 
fIeld dpt dept desc 
field dpt-builaing 
field dpt:address 


end 
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type 
type 
type 
type 


integer 
character 
character 
character 


length 40 
length 25 
length 25 
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database company 
end 


output 
report to "salary.rpt" 
top margin 6 
end 


{ Read the employee information } 
{ from the employee file. 
} 


read 


end 


into a employees dpt dept desc 
{Select only those who are currently employed.} 
where emp status • "en 
{ Join the employee information 
} 
{ with each employee's department name.} 
joining emp_dept_num • dpt_dept_num 


{ Sort the result by the employee's name. 


sort by dpt_dept_desc emp_name end 
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format 


on every record 


print 25 spaces,"SALARY REVIEW" 
skip 3 lines 


print "Name: ",emp name, 2 spaces, 
"Date Employed: ", 
emp hire date 
skip 1 line 
- 


print "Date of Last Review: ", 
emp last review date 
2 spaces7 
- 
"Employee II : 
/I, emp_number 
using "1111##/1 


skip 1 line 


print "Present Rate: ", emp salary 
using "$$$,$$$.##/1 - 
skip 1 line 


print "Recommended New Rate: 
/I; 


if (emp rating = "poor") 
then-print emp_salary * 1.00, 
using "$$$,$$$.11#/1 


if (emp rating = "fair") 
then-print emp_salary * 1.05 
using "$$$,$$$.##/1 
if (emp rating = "good") 
then-print emp salary * 1.10 
using /1$$$,$$$.##/1 
if (emp rating = "superior") 
then-print emp salary * 1.15 
using /1$$$,$$$.##/1 


skip 
1 line 


print "Date effective: ", 
emp_salary_effective_date 


skip 1 line 


print "Department: ",dpt_dept_desc 
skip 1 line 
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print 
"Position and Responsibilities: ", emp_titIe 
skip 8 lines 


print 
"New Position and/or Responsibilities recommended:" 
skip 8 lines 


print "Comments:" 
skip 8 lines 


print 
"Supervisor's Signature 
skip 1 line 


print 
"Personnel Manager's Signature 
skip 1 line 


print 
"Operation Manager's Signature 


skip to top of page 


end 
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VI.B. 
Writing Checks 


This example shows a payroll situation in which 
some of the calculations have already been per- 
formed. 


For example, taxes such as social security and 
state disability have already been calculated for 
the payroll file. 
These figures are already in the 
database for the given pay period. 
The task of this 
ACE program is to summarize this information on a 
payroll check stub and then partially fill out the 
check. 


This printing is destined for checks that have 
a vertical format, with the check stub attached to 
the top of the check itself. 


The desired output for this program is shown below: 


649.25 


the period ending 01/15/82 
13.25 
530.00 
19.88 
119.25 
Earnings: 


For 
40 
6 
Total 


51.81 
132.30 
10.23 
37.20 


Total Deductions: 
231.54 


01/15/82 


John Jones 
***417.71 
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The top part of this output would be printed on 
the check stub; the lower part would partially fill 
out the check itself. 
The check could then be veri- 
fied, completed and signed by hand, or by an au- 
tomatic check signing and protecting machine. 


The payroll schema containing most of the in- 
formation used by this ACE program is shown on the 
next page. 


database cOMpany 
tile payroll 
tield pay_eMployee_number 
tield pay-period_ending 
tield pay salaried 
tield pay-salary 
tield pay:reg_hours 
tield pay_reg_rate 
tield pay over hours 
tield pay-over-rate 
tield pay-ss tax 
tield pay-ted withhold 
tield paY-sdC 
tield pay-st withhold 
end 
-- 


type 
type 
type 
type 
type 
type 
type 
type 
type 
type 
type 
type 


integer 
date 
character length 1{"y" or An"} 
double fbi-monthly salary} 
double {regular hours worked} 
double {regular rate per hour} 
double {overtime hours worked} 
double {overtime rate per hour} 
double {social security tax} 
double {federal withholding} 
double {state disability insur.} 
double {state withholding} 


The ACE program uses the eaployees file (shown 
previously) to get the employee's name, based upon 
the employee number in the payroll file. 


The ACE program selects the fields from the 
payroll file for the current pay period. 
The pay 
period ending date is transmitted to the program by 
the user through ACE's parameter passing facility. 


INFORMIX 
115 


ACE Relational Report Writer 


database company 
end 
{Period 
endin~ date must be typed on the 


commana line} 
define 
param[1] 
period_ending 
type date 
end 
output 
report to "checks.rpt" 
end 
read payroll emp name 


where pay period ending = period ending 
joining pay employee number = emp number 
end 
• 
- 
- 
- 


format 
on every record 
print "For the period ending ", 
period ending 
print pay_reg_hours 
using "##&", 
5 spaces, 


pay_reg_rate 
using "##.##", 
3 spaces, 
pay reg hours 
-*- 
pay_reg_rate 
using "###&.&&" 
print pay over hours using "##&", 
5 spaces, 
pay-over-rate 
- * 
- 
pay_reg_rate 
using "##.##", 
3 spaces, 
pay over hours 
- * 
- 


"##&.&&" 
"##&.&&" 
"##&.&&" 
"##&.&&" 


using 
using 
using 
using 


pay reg rate 
- * - 
pay_over_rate 
using "###&.&&" 
print "Total Earnings:", 
11 spaces, 
(pay_reg_hours * pay_reg_rate) 
• 
(pay over hours * pay reg rate * pay over rate) 
- 
- 
using "#"11#&.&&" 
-- 
skip 1 line 
print pay ss tax 
print pay-fea withhold 
print pay:sdi- 
print pay st withhold 
print 
-- 
print "Total Deductions:", 
9 spaces, 
pay ss tax 
• pay fed withhold 
"+ pay-sdi- 
• pay:st_withhold 
using "###&.&&" 
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{Now print the body of the check itself.} 
skip 8 lines 
print 45 spaces, 
period_ending 
skip 1 line 
print 11 spaces, emp name, 
(pay_reg_hours * pay_reg_rate) 
+ 
(pay over hours * pay_reg_rate * 
pay_over_rate) 


(pay ss tax 
+ pay fed withhold 
+ 


pay sdl 
+ pay st withhold) 
using-"******.&I" - 
end 
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VI.C. 
Inventory Control 


This example shows a customized inventory re- 
port which lists all of the items in the inventory 
(binders, pens, etc.) and checks each category to 
see what re-ordering is needed. 
If re-ordering is 
needed, the names and addresses of the suppliers of 
the items will be printed immediately for the con- 
venience of the inventory manager. 


Two pages of a typical run of this report are 
shown here. 


••••••••••••••••*••••• 
• 
Inventory Report 
* 
•••••••**•••••••**•••• 


Itelll 


4 x 6 tablets 
Apollo #2 Pencils 
Binders 
Bridgeport Pens 
Erasers 


On 
Back 
Hand Ordered 
25 
17 
100 
0 
350 
150 
10 
5 
6 
12 


t.ead TilDe 
(days) 
15 
5 
10 
10 
30 


Reorder 
Point 
20 
20 
300 
10 
30 **Reorder*· 


(211) 555-1778 


Vendors tor the itelll Erasers 


Paper Distributors ot Alllerica 
271 'fl. 
Landon 
St. 
Louis, 
MO 
Hal Gibson 
(313) 555-3423 


Tablets ! Stull 
98132 Madison Ave 
New York, 
NY 
Bill Davia 


Venus Pencil ! 
Pen Co 


444 'fl. 
'fIash1ngton St 
San Francisco, 
CA 
Sally 'fIarren 
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•••••••••••••••••••••• 
• 
Inventory Report 
• 
•••••••••••••••••••••• 


Item 
On 
Back 
Lead Time Reorder 


Hand Ordered (days) 
Point 
Paper Clips 
2 
0 
10 
200 ··Reorder" 


Vendors for the item Paper Clips 


Tablets ! Stu!!' 
98132 Madison Ave 
Nev York, 
NY 
Bill Davis 


The Paper Company 
74633 Venice Blvd 
Los Angeles, 
CA 
Mary Johnson 


Venus Pencil ! 
Pen Co 
444 W. 
WaShington St 
San Francisco, 
CA 
Sally Warren 


(213) 555-2233 


(415) 555-1122 


The ACE program to produce this report accessed 
three files using two READ statements, each with a 
JOIN. 
Here are the schemas for the three files: 


database company 
file inventory 
field inv item number 
field inv-on hand 
field inv-back ordered 
field inv-Ieadtime 
field inv:reorder-point 
end 
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type 
type 
type 
type 
type 


integer 
integer 
integer 
integer 
integer 
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database company 
file vendors 
field ven_number 
type integer 
field ven name 
type character 
length 30 
field ven-address 
type character 
length 25 
field ven-city 
type character 
length 25 
field ven-state 
type character 
length 2 
field ven-representative type character 
length 25 
field ven:phone 
type character 
length 20 
end 


field 
field 
end 


database company 
file goods 
field gds item number type integer 
field gds-item-desc 
type character 
field gds-vendor number 
- 
- 
type integer 
field gds vendor item number 
- 
~ 
-type character 
gds_price 
type double 
gds_terms 
type character 


length 30 


length 15 


length 10 


The data that was in the inventory file at the 
time this report was run is shown below. 


inv item number 
inv-on hand 
inv-back ordered 
inv-leadtime 
inv:reorder_poi~t 


Inv item number 
inv-on hand 
inv-back ordered 
inv-leadtime 
inv:reorder_point 


120 


101 
10 
5 
10 
10 


102 
25 
17 
15 
20 
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inv item number 
103 
inv-on hand 
100 
inv-back ordered 
0 
inv-leadtime 
5 
inv:reorder_point 
20 


inv item number 
104 
inv-on hand 
2 
inv-back ordered 
0 
inv-leadtime 
10 
inv:reorder_point 
200 


inv item number 
105 
inv-on hand 
350 
inv-back ordered 
150 
inv-leadtime 
10 
inv:reorder_point 
300 


inv item number 
106 
inv-on hand 
6 
inv-back ordered 
12 
inv-leadtime 
30 
inv:reorder_point 
30 


The data that was in the goods file at the time 
the report was run is as follows. 


gds item number 
gds-item-desc 
gd~-vendor number 
gds-vendor-item number 
gds~rice - 
- 
gds_terms 
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101 
Bridgeport Pens 
1001 
BP 132-001 
1.500000 
10/n30 
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gds item number 
gds-i tem-dese 
gds-vendor number 
gds-vendor-item number 
gds-priee- 
- 
gds:terms 


gds item number 
gds-item-desc 
gds-vendor number 
gds-vendor-item number 
gas-price - 
- 
gds:terms 


gds item number 
gds-item-desc 
gds-vendor number 
gds-vendor-item number 
gds-price - 
- 
gds:terms 


gds item number 
gds-item-desc 
gds-vendor number 
gds-vendor-item number 
gds-price - 
- 
gds:terms 


gds item number 
gds-item-desc 
gds-vendor number 
gds-vendor-item number 
gds-price - 
- 
gds:terms 


122 


101 
Br idgeport Pens 
1002 
1324-a 
1.520000 
15/n30 


106 
Erasers 
1001 
112-100 
5.000000 
10/n30 


106 
Erasers 
1003 
112-112 
4.500000 
10/n30 


106 
Erasers 
·1004 
112-110 
4.500000 
10/n30 


104 
Paper Clips 
1004 
003-723 
4.500000 
10/n30 
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gds item number 
gds-item-desc 
gds-vendor number 
gds:vendor:item_number 
gdsJrice 
gds_terms 


gds item number 
gds-item-desc 
gds-vendor number 
gds-vendor-item number 
gds~rice - 
- 
gds_terms 


gds item number 
gds-item-desc 
gds-vendor number 
gds-vendor-item number 
gds-price - 
- 
gds-terms 


gds item number 
gds-item-desc 
gds-vendor number 
gds-vendor-item number 
gds~rice - 
- 
gds_terms 


gds item number 
gds-item-desc 
gds-vendor number 
gds-vendor-item number 
gds-price - 
- 
gds:terms 
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104 
Paper Clips 
1002 
570-73c 
4.500000 
10/n30 


104 
Paper Clips 
1003 
570-75c 
4.750000 
10/n30 


102 
4 x 6 tablets 
1002 


0.000000 


103 
Apollo #2 Pencils 
1003 


0.000000 


105 
Binders 
1004 


0.000000- 


The contents of the vendors file at the time 
the report was written is shown below. 
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yen number 
yen name 
yen-address 
yen-city 
yen-state 
yen-representative 
ven:phone 


Yen_number 
yen name 
yen-address 
yen-city 
yen-state 
yen-representative 
ven:phone 


Yen_number 
yen name 
yen-address 
yen-city 
yen-state 
yen-representative 
ven:phone 


Yen_number 
yen name 
.ven-address 
yen-city 
yen-state 
yen-representative 
ven:phone 


1001 
Paper Distributors of America 
271 W. 
Landon 
St. Louis 
MO 
Hal Gibson 
(313) 555-3423 


1002 
The Paper Company 
74633 Venice Blvd 
Los Angeles 
CA 
Mary Johnson 
(213) 555-2233 


1003 
Venus Pencil & Pen Co 
444 W. 
Washington St 
San Francisco 
CA 
Sally Warren 
(415) 555-1122 


1004 
Tablets & Stuff 
98132 Madison Ave 
New York 
NY 
Bill Davis 
(211) 555-1778 


The ACE program that produced the report is now 
shown. 
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{inventory report #1} 
database company 
end 


output 
report to "invent1.rpt" 
end 


read into temp gds item desc, 
gds-vendor number, 
gds-price,- 
gds-terms, 
inv-on hand, 
inv-back ordered, 
inv-leadtime, 
inv:reorder_point 
ven name, 
ven-address, 
ven-city, 
ven-state, 
ven-representative, 
ven-phone 
JOlnlng gds item number 
= inv item number 
and gds_vendor_number = ven_number- 
end 
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" 


ven name 
ven- address 
ven-city Without trailing blanks, ". ", 


ven state 
ven_representative, ven-phone 


"Item", 26 spaces, 
"On 
", 
"Back 
", 
"Lead Time ", 
"Reorder 
" 
print 30 spaces, 
" 
Hand", 
"Ordered ". 
"(days) 
", 
"Point 
skip 1 line 
before group of gds item desc 
print gds item deac, 
- 


inv on nand 
using "NNNN& 
" • 


inv-bac'k ordered 
'using "NNNN& 
". 
inv:leadtime 
using "NNNN& 
". 
inv reorder point 
using" 
NNNN& 
"; 
if (inv on-hand < Inv reorder point) 
then 
- 
- 
- 
- 
begin 
print "**Reorder**" 
print 
print "Vendors for the item ", gds_item_desc 
print 
end 
else 
print 
on every record 
if (inv on hand < inv_re~rder_point) 
then 
-- 
begin 
print 
print 
print 


print 
print 
end 
after group of gds item deac 
if (inv on hand < inv:reorder_point) 
then 
-- 
skip to top of page 


format 
page header 
print 20 spaces, 
"**********************" 
print 20 spaces,"* 
Inventory Report 
*" 
print 20 spaces, "**********************" 
print 
print 


end 
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VI.D. 
Real Estate 


This example gives a real estate broker the 
ability to examine a database of real estate list- 
ings and get a printout of the homes that are below 
the customer's maximum price. 


The file, listings, contains the basic informa- 
tion about the home and some descriptive informa- 
tion. 


The output of the report is shown below • 


.•.............•..•..... 
• Re.idential Listings • 
• 
Ceiling Prie. 
• 
• 
$145.000.00 
• 
•....................... 


HUll City 
Addr.ss 


56 Buck Cr.ek 
7534 Shady Lane 


COII.ents: 
Rural setting. s••ll .tr•••• 


108 M.diaon 
543 W. 
Hillsdaie 
Co_nta: 
CORNER LOT 
He~ carpets snd dr.pery 
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2 


1.00 
$145.000.00 


2 
0.50 
$140.000.00 
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The listings schema is shown below. 


database realty 


file listings 


field listing_number 
type integer 
field address 
type character 20 
field city 
type character 20 
field footage 
type integer 
field bedrooms 
type integer 


field baths 
type integer 


f'ield lot size 
type double 
field corner lot 
type character 1 


field schools 
type character 1 


field asking_price 
type money 
field sales_price 
type money 
field broker 
type character 15 
field listing_note1 
type character 45 


end 
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The report prompts the user for the highest 
price that the buyer will pay, and uses this figure 
in the WHERE clause of the READ statement to select 
the proper records from the listings file. 


{listings1} 


database realty 
end 


define 
variable highest_desirable_price 
type money 
end 


{At the beginning of ACEGO, ask the user for the 
{price to be searched for in the database. 
} 


input 


prompt for highest desirable_price 
using "Enter hignest desirable price > " 
end 


output 
report to "listings1.rpt" 
end 


{Find all the houses in the listings file vhich} 
{have a price less than or equal to the user-input} 
{price held in the user variable highest_desirable-price.} 


read into a all of listings where 
aSking_price <- highest_desirable_price 
end 


sort by listing_number 
end 
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format 


page header 
print 20 spaces,"························" 
print 20 spaces,"· Residential Listings ." 
print 20 spaces,"· 
Ceiling Price 
." 
print 20 spaces,"· 
", 
highest_desirable_price 
using" 
SSSS,SSS.!!", 


" 
." 
print 20 spaces,"························" 
print 
print" 
Mum City 
Address", 
" 
Bedrm Baths Acres 
Price" 
print 


before group of listing_number 


print listing_number using "111##"," ",city[1,10], 
address, bedrooms,baths,lot size 
using "###!.!!",3 spaces, 
- 


listing-price using "SSSS,SSS.##" 
print 
print "Comments:" 
if (corner_lot .. "yO or corner lot .. "Y") then print "CORNER LOT" 
if (schools .. "yO or schools .-"Y") 
then print "NEAR SCHOOLS" 


on every record 


if (listing_note1 !. " "}then print listing_note1[1,45] 


after group of listing_number 


Skip 2 lines 


.end 
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VI. E. 
Bank Reports 


The following examples draw on the bank data- 
base. 
The schemas are reprinted below. 


{LOAN SCHEMA} 


database bank 


file loan 
. 
field loan num 
type serial start 1000 index primary 
field borr-num 
type long 
index dups 
field loan-date 
type date 
field loan-type 
type char 
length 15 
field loan-amt 
type money 
field primaryoff type long 
field secondof! 
type long 
field term type 
type char 
length 2 
field rate- 
type double 


end 


{BANKCUST SCHEMA} 


database bank 


file bankcust 


field cust num 
type serial 
index 
field cust-lname 
type char 
length 15 
field cust-fname 
type char 
length 10 
field cust-addr 
type char 
length 20 
field c:ust-city 
type char 
length 15 
field state 
type char 
length 2 
field zip 
type char 
length 5 
field c:ustJhone 
type char 
length 18 
field employer 
type char 
length 25 
field salary 
type money 
field hired 
type date 
field c:o_app 
type long 


end 
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{EMPLOYEE SCHEMA} 


database bank 


f11e employee 


fie ld emp num 
type serial 
index 
field emp-lname 
type char 
length 15 
field emp-fname 
type char 
length 10 
field emp-addr 
type char 
length 20 
field emp-city 
type char 
length 15 
field emp-phone 
type char 
length 13 
field emp-hired 
type date 
field emp-dept 
type integer 
index dups 


field amp-title 
type char 
length 20 
field emp:salary 
type money 


end 


{DEPARTMENT SCHEMA} 


database bank 
file depat'tment 


field dept num 
field dept-name 
field dept:mngr 


end 


type integer 
type char 
type long 


index 
length 20 


The following report may be used to retrieve 
data about a selected group of bank employees. 
In 
this case, the report selects employees whose salary 
is greater than the ~verage salary plus ten percent. 
An index was added for the field emp salary to allow 
a sort on the field in an optimized read. 
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database bank end 


define 
variable av type money 
variable ten type money 
end 


output 
report to "salary.rpt" 
end 
let av • average of emp_salary end 
let ten = av * 1.10 end 


read into x 
employee where emp_salary > ten 
end 


sort by amp_salary 
end 


format 
first page header 
print "Report on Employee Salaries" 
skip 3 lines 
print "The Average Salary is : 
print "Ten Percent Over Average is 
skip 3 lines 


", av 
", ten 


print 2 spaces, "Employee Name", 17 spaces, "Salary" 
skip 1 line 


on every record 
print emp_fname, emp_lname, emp_salary 
end 


The output report is printed on the following 
page. 
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Re!-,urt on Employee Salaries 


The Average Salary is : 
Ten Percent Over Average is 


Employee Name 


$28225.00 
$31047.50 


Salary 


Peter 
Marion 
James 
Dolores 
Donald 


Henderson 
Fernandez 
Pearson 
Pinter 
Jackson 


$35000.00 
$35500.00 
$36800.00 
$37000.00 
$42500.00 


The report that follows will provide employer 
and salary information on applicants and co- 
applicants, adding salaries where two applicants are 
applying for one loan, and sorting by the total of 
salary. 


database bank 
end 


output 
report to "cust.rpt" 
end 


alias cus • bankcust end 


read 


end 


into temp 
cust num, employer, salary, co_app, 
coapp emp • cus.employer, 
coapp-sal • cus.salary, 
newsar • salary 
+ cus.salary 
joining co_app • optional cus.cust_num 


sort by newsal end 
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format 
first page header 
print 
"Applicant and Co-applicant Employer and Salary." 
skip 3 lines 


... 41" 


on every record 
skip 2 lines 
print "Customer 
print "Employer 
print "Salary 
skip 1 line· 


Number: ", 
", 
", 


2 spaces, cust num 
8 spaces, employer 
2 spaces, salary 


is no co-applicant." 


"Co-applicant 
"Employer 
"Salary 


if co app = 0 


then pr int 
"There 
else 
begin 
print 
print 
print 
end 


skip 1 line 
print "Total Salary 


end 


", 
2 spaces, co_app 
", 8 spaces, coapp emp 
", 
2 spaces, coapp:sal 


", 2 spaces, newsal 


The output report is printed below. 


Applicant and Co-applicant Employer and Salary. 


Customer Number: 
Employer 
Salary : 


8 
Corner Deli 
$15500.00 


There is no co-applicant. 


Total Salary : 
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Customer Number: 
Employer 
Salary : 


1 
All Sports Supplies 
$21000.00 


There is no co-applicant. 


Total Salary : 


Customer Number: 
Employer 
Salary : 


$21000.00 


10 
Cole's Refrigeration 
$21000.00 


There is no co-applicant. 


Customer Number: 
Employer 
Salary : 


7 
Master Systems 
$23000.00 


There is no co-applicant. 


Total Salary : 


Customer Number: 
Employer 
Salary : 


$23000.00 


20 
Wilson Plumbing 
$26000.00 


There is no co-applicant. 


Total Salary : 


Customer Number: 
Employer 
Salary : 


$26000.00 


3 
Stanford University 
$34500.00 


There is no co-applicant. 


Total Salary : 
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5 
Xyntechnix 
$34500.00 


There is no co-applicant. 


Total Salary : 


Customer Number: 
Employer 
Salary : 


$34500.00 


4 
Zytyx 
$43000.00 


There is no co-applicant. 


Total Salary : 


Customer Number: 
Employer 
Salary : 


$43000.00 


2 
City of San Francisco 
$45000.00 


There is no co-applicant. 


Total Salary : 


Customer Number: 
Employer 
Salary : 


Co-applicant 
Employer : 
Salary : 


Total Salary 
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21 
Newtech Research 
$32000.00 


22 
Sims' Menswear 
$19500.00 


$51500.00 
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Customer Number: 
Employer 
Salary : 


Co-applicant 
Employer : 
Salary : 


Total Salary 


Customer Number: 
Employer 
Salary : 


Co-applicant 
Employer : 
Salary : 


Total Salary 


Customer Number: 
Employer 
Salary : 


Co-applicant 
Employer : 
Salary : 


Total Salary 


Customer Number: 
Employer 
Salary : 


22 
Sims' Menswear 
$19500.00 


21 
Newtech Research 
$32000.00 


$51500.00 


13 
Sante Fe Grill 
$19500.00 


14 
Pearson Investments 
$33800.00 


$53300.00 


14 
Pearson Investments 
$33800.00 


13 
Sante Fe Grill 
$19500.00 


$53300.00 


6 
Nuclear Technology 
$58000.00 


There is no co-applicant. 


Total Salary : 
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Co-appUcant 
Employer : 
Salary : 


Total Salary 


Customer Number: 
Employer 
Salary : 


Co-applicant 
Employer : 
Salary : 


Total Salary 


Customer Number: 
Employer 
Salary : 
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11 
Developmental Technology 
$34000.00 


12 
Super Software 
$46000.00 


$80000.00 


12 
Super Software 
$46000.00 


11 
Developmental Technology 
$34000.00 


$80000.00 


9 
Muley Enterprises 
$185000.00 


There is no co-applicant. 


Total Salary : 
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VII. 
Advanced Features 


VII.A. 
The FOR Loop 


The FOR loop controls a statement, or a set of 
several statements (a compound statement). 
A com- 
pound statement block begins with the keyword BEGIN 
and ends with the keyword END. 
A compound statement 
block may contain any number of other simple or com- 
pound statements. 


The structure of the FOR statement is as fol- 
lows: 


FOR indexvariable • exp TO exp [STEP exp] 
DO statement 


where exp is a general arithmetic expression, state- 
ment is a simple or compound statement, and the op- 
tional step expression is the amount to be added to 
the index variable on each iteration of the loop. 
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VII.B. 
The WHILE Loop 


The WHILE loop evaluates an expression as ei- 
ther true (non-zero) or false (zero), and takes some 
action based on the evaluation: 


WHILE exp DO statement 


where exp is any logical expression (an expression 
which evaluates either true or false), and statement 
is a simple or compound statement. 
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VII.C. 
Calling C Subroutines 


The ability to call C functions from ACE gives 
the ACE programmer the flexibility to produce spe- 
cial reports. 
For example, you would call a C sub- 
routine in order to obtain trigonometric math func- 
tions. 


With the "user function" feature of ACE, any 
math function, or any other C subroutine, can be 
linked into ACE and used in ACE programs. 
In the 
example given below, a user function to pass a 
string of characters to an operating system shell 
will be called. 
The operating system's "system" 
subroutine will be used to perform the actual pass- 
ing, but the C code which gives the string to this 
operating system routine must be made known to 
ACEPREP and linked into ACEGO. 
The ACE program 


which utilizes the user function is shown on the 
next page. 


Refer to the subsequent discussion for informa- 
tion on how to compile, load, and use a C subrou- 
tine. 
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database stores end 


define 


function tounix 
end 


read orders end 


format 
on last record 
call tounix( "Is> functest3. rpt") 
end 


Here the user function is called "tounix". 
It 
is made known to ACEPREP through its declaration in 
the DEFINE command. 
The C code which composes 
"tounix" is shown below. 


#include "ace.h" 


extern acevalue tounix(); 
struct ufunc userfuncs[] = 
{ 
"tounix", tounix, 
0,0 
} ; 


acevalue tounix(string) 
acevalue string; 


{ 
char 
savearea[80]; 


rbytecpy(string->v charp, savearea, string->v len); 
/*copy bytes from string to savearea*/ 
- 
savearea[string->v len]=O; /*put null on end*/ 
system(savearea); - 
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This code includes the ace.h header file, which 
will be described later. 
It then externs the name 
of the function. 
This is done so that in the 
definition of the "userfuncs" array of structures, 
the C compiler will know that the entry correspond- 
ing to the string "tounix" is a function. 
As many 
functions as desired may be placed in the "user- 
funcs" array. 
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The ace.h header file is shown below, and ex- 
plained on the next page. 


/* 
* This 1s the file which must be included 
* in any C subroutine source 
* file which is to be linked to libace.a. 
*/ 


Idefine CHARTYPE 
Idefine INTTYPE 
Idefine LONGTYPE 
Idefine DOUBLETYPE 
Idefine FLOATTYPE 
Idefine SERIALTYPE 
Idefine SERIALSIZE 
Idefine DATETYPE 
#define EDATETYPE 
#define YDATETYPE 
#define DATESIZE 
#define MONEYTYPE 
#define MONEYSIZE 


o 
1 
2 
3 
4(Ox0100 + LONGTYPE) 
LONGSIZE 
(Ox0200 + LONGTYPE) 
(Ox0300 
+ LONGTYPE) 
(Ox0400 + LONGTYPE) 
LONGSIZE 
(Ox0500 + DOUBLETYPE) 
DOUBLESIZE 


/* integer value*/ 
value (also dates)*/ 
/* float value*/ 
value (also money)*/ 


/* long 


/* double 


v val.vchar.vcp 
v-val.vchar.vidx 
v-val.vchar.vlen 
v-val. vint 
v:val.vlng 
v val.vflo 
v:vaLvdub 


/* type of value, determines*/ 
/* which of following is valid*/ 


/* char value (not null terminated)*/ 


/* ptr to char string value*/ 
vidx; 
/* unused */ 
/* len of char string value*/ 


{ 
struct 
{ 
char 


struct value 
{ 
short v_type; 
union 


*vcp; 
short 
short vlen; 
} vchar; 
int vint; 
long vlng; 
float vflo; 
double vdub; 
} v val; 
}"; 
#define v charp 
#define v-index 
#define v-len 
#define v-int 
Idefine v-long 
Idefine v-float 
#define v:double 


extern double floor(), ceil(), fabs(); 
extern double round(); 
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/** the following defines are for money types 
* money is stored as cents in a double value 
* CENTS converts a double value of dollars to 
* money type (cents) 
DOLLARS converts a money 
* type (cents) to double (dollars) 
* ROUND just rounds a value to integral number 
*/ 
#define CENTS(d) 
(ROUND(d*100.0)) 
#define DOLLARS(c) (c/100.0) 
#define ROUND(c) 
round(c) 


typedef struct value * acevalue; 
extern struct value retstack; 


#define intreturn(i) 


#define lngreturn(i) 


#define floreturn(d) 


#define dubreturn(d) 


#define strreturn(s,c) 


retstack.v type=INTTYPE;\ 
retstack.v-int=(i);\ 
return(&retstack) 


retstack.v type=LONGTYPE;\ 
retstack.v-long=(i);\ 
return(&retstack) 


retstack.v type=FLOATTYPE;\ 
retstack.v-float=(d);\ 
return(&retstack) 


retstack.v type=DOUBLETYPE;\ 
retstack.v-double=(d);\ 
return(&retstack) 


retstack.v type=CHARTYPE;\ 
retstack.v-charp=(s);\ 
retstack.v-len=(c);\ 
return(&retstack) 


integer) 


extern int toint(); 
/* toint() takes a pointer to value 
* 
structure as an argument. 
* 
Returns the value (converted to 
* 
of the value structure (v_int). 
*/ 
extern long tolong(); 
/* tolong() takes a pointer to value 
* 
structure as an argument. 
* 
Returns the value (converted to long) 
* 
of the value structure (v_long). 
*/ 
extern double todouble(); 
/* todouble() takes a pointer to value 
* 
structure as an argument. 
* 
Returns the value (converted to double) 
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**/ 
extern long todate(); 
/* todate() takes a pointer to value 
* 
structure (1st arg) and a type 
* 
(2nd arg). 
* 
Returns the value (converted to long) 
* 
ot the value structure (v long). 
* 
The type is used only if the value was a 
* 
CHARACTER type -- it is set to DATETYPE, 
* 
YDATETYPE, or EDATETYPE 
*/ 
extern' double tomoney(); 
/* tomoney() takes a pointer to value structure 
* 
as an argument. 
* 
Returns the value (converted to double) 
* 
of the value structure (v_double). 
*/ 
extern double tofloat(); 
/* totloat() takes a pointer to value structure 
* 
as an argument. 
* 
Returns the value (converted to double) 
* 
ot the value structure (v double). 
*/ 
- 


struct ufunc 
{ 
char *uf id; 
struct value *(*ut_func)(); 
} ; 
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The structure declaration for "userfuncs" must 
be put in the user's data area. 
A hypothetical case 
using the user C functions called "userfunc1" and 
"userfunc2" is shown below. 


extern acevalue userfunc1(); 
These routines must be 
; 
externed 
extern acevalue userfunc2(); 
before the userfuncs 
structure is 
initial1zed 


Pointer to the user 
---------- 
function. 
The name of the user 
----------------------- 
function as defined in 
the DEFINE statement of 
ACE. 
<---------------------Note that this array must 
be terminated by two 
zeros. 


0,0 


struct ufunc userfuncs() 
= 
{ 
"userfunc1", userfunc1, 
"userfunc2", userfunc2, 
.. 
.. 


} ; 


These structures are required so that ACE can 
call the user subroutines at run-time. 


Despite the apparent complexity of the ace.h 
file, it is designed to make the process of inter- 
facing C routines to ACE fairly easy for the pro- 
grammer. 
For example, the defines shown below can 
be used to detect the data type of the parameter 
passed to the C function, and to get the value of 
the parameter, whether it is an integer, double or a 
character string. 


v charp 
v-len 
v-int 
v-long 
v-float 
v-double 
v:type 


pointer to string 
length 
integer value 
long value 
float value 
double value 
type of the parameter 


You can determine the data type of the parame- 
ter by checking v_type, then obtaining the appropri- 
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ate value. 
If v type is CHARTYPE, then the pointer 
to the string is-available in v charp, and the 
number of characters in the strIng (length) is 
available in v len. 
The string is NOT null- 
terminated; it-is terminated by O. 


Since expressions could be passed from ACE in- 
stead of simple numbers or variables, the type 
should be checked. 
However, the functions "toint" 
and "todouble" can make this unnecessary and make 
the mechanics of parameter passing simpler overall. 


The-following example shows an ACE program that 
will call a C routine to make use of the square root 
function: 


{functest2} 
database stores end 


define 
function squareroot 
variable dub 
type double 
end 


output 
report to "functest2.rpt" 
end 


read into a orders 
end 


format 
page header 
print "Item", 9 spaces, 
"Quantity", 2 spaces, 
"sqrt(quantity)" 
skip 2 lines 


on every record 
let dub 
= quantity 
print item, quantity using "######w, 


2 spaces, 
squareroot(dub) using "##.#####" 
end 


The C routine to be called is shown on the next 
page. 
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#include "ace.h" 
#include <math.h> 


extern acevalue squareroot(); 


struct ufunc userfuncs(] 
= 
{ 
"squareroot", squareroot, 
0,0 
} ; 


/*---- User Functions -----*/ 


acevalue squareroot(pnum) 


acevalue pnum; 


{ 


} 
dubreturn(sqrt(pnum->v_double»; 


Notice the formal parameters of the function 
were declared to be of type acevalue, using the 
typedefs in the ace.h file. 
Thus, the value with 
the structures described in the ace.h file can be 
accessed simply by addressing them as the field of a 
structure, as shown in the expression below. 


pnum->v~double 


This could also have been addressed without the 
need for type checking by using the "todouble" func- 
tion, as shown. 


todouble(pnum) 


The "toint" and "todouble" functions will per- 
form needed type conversions. 


When the report shown above is run, the output 
is as follows. 
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Item 
Quantity 
sqrt( quantity) 


Work Bench 
5 
2.23607 
Saw 
1 
1.00000 
Work Bench 
3 
1.73205 
File 
3 
1.73205 
Hammer 
8 
2.82843 
Saw 
3 
1.73205 
File 
5 
2.23607 
File 
1 
1.00000 
Hammer 
2 
1.41421 


C functions can be called from ACE using the 
CALL function name syntax, or by just using the 
function name 1n an expression. 
When the GALL func- 
tionname syntax is used, 
ACE does not expect a value 
to be returned from the function. 
However, when a C 
function is called without the use of CALL, it must 
return a value to ACE. 


The following defines are available to return a 
value to an ACE 
~rogram. 


intreturn(i) 
dubreturn(d) 
strreturn(s,c) 
lngreturn(i) 
floreturn(d) 


"intreturn" is used to return an integer, "du- 
breturn" is used to return a double, and "strreturn" 
is used to return a pointer to a string, as well as 
the length of the string. 
Again, returned string 
values are not null terminated. 
"lngreturn" is used 
to return a long, and "floreturn" is used to return 
a float • 


. Two conversion routines are also available for 
the C function to use if it knows the data type of a 
number that it is expecting. 
The "toint" function 
can be used and will 
~eturn an integer value, and 
the "todouble ll function can be used and will return 
a double value, regardless of ACE's evaluation of an 
expression. 


For example, an integer value can be converted 
to a double value upon return in the following 
manner: 
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acevalue fromace; 
. 
dubreturn(todouble(fromace»; 


Once the file containing the user function it- 
self is compiled, a special version of ACEGO must be 
generated which knows about the function. 
This is 
done as shown below. 
Once a version of ACEGO has 
received the custom expansion, it may be used to run 
ACE programs which make 
u~e of user functions. 


~ cc userfunc.c -lace -ldb -1m -0 newacego 


The -lace flag retrieves the ACE library, 
/usr/lib/libace.a. 


The -1db flag retrieves the access method and 
RDS subroutines needed by ACE. 


The -1m flag retrieves the math library func- 
tions, if any, called by a user function. 


On some operating systems, flags such as -1 may 
be needed to compile the ACEGO program to use the 
memory as "split I/O." The file containing the user 
function need not be called 
user~unc.c. 


After this compilation, use newacego in place 


of acego. 
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VII.D. 
Calling C Subroutines with MS-DOS 


The MS-DOS C programmers' package for the ACE 
program consists of the files llbace.l1b and ace.h. 
The files rdsmain.c and rdsmaln.obj are also a part 
of the C programmers' package. 


To use these C language programming tools, you 
must have the Lattice C compiler version 2.0. 
Com- 
pile your C programs with Lattice 2.0 using the P- 
model option, and link them with the Lattice P-model 
l~brary and the RDS ACE library. 


To compile and link a C program called usertunc 


with ACE, give the commands 


>lc1 userfunc -mp 
>lc2 userfunc 
>link cp+userfunc+rdsmain,userfunc"libace+lcp 
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VII.E. 
Compatibility with Previous Versions of ACE 


In the past, the PARAM[X] expression could be used 
'without a variable name. 
Now, these parameters must 
have a variable name associated with them as 
described earlier. 


Other incompatibilities between versions do not 
involve changes to the syntax of the language it- 
self, but rather the intermediate files which are 
generated by ACEPREP and interpreted by ACEGO. 
As 
the number and types of statements have grown, the 
representation of these statements in their compiled 
form in the .arc file has changed. 
Therefore, 
ACEGO 
has been programmed to check that the .arc file it 
is about to execute was created by a version of 
ACEPREP that it can interpret. 
If ACE cannot inter- 
pret the .arc file, a version number incompatibility 
error will be printed. 
If a version number incompatibility error oc- 
curs, you must recompile the ACE program with the 
version of ACEPREP which was delivered with the ver- 
sion of ACEGO that is being run. 


154 
INF.ORMIX 


ACE Relational Report Writer 


VIII. 
Appendix - Error Messages 


ACEPREP 


error 8001: 


The number of newlines specified for TOP MARGIN, 
FIRST PAGE HEADER (page header), 
PAGE TRAILER, and 
BOTTOM MARGIN must leave enough room on the page for 
the printing of the ON EVERY RECORD clause. 


error 8002: 


The ACE report specification is too complex or large 
to be properly compiled. 
The number of instructions 
needed to implement this specification is greater 
than the space allocated in the compiler's instruc- 
tion tables. 


error 8003: 


An INTEGER constant may not be larger than 32767. 


error 8004: 


Illegal DOUBLE constant. 


error 8006: 


A quoted string may not exceed 4000 characters in 
length. 


error 8008: 


The file specified could not be opened. 
The operat- 
ing system was asked to open it for reading. 


error 8010: 


The file specified could not be opened. 
This is an 
internal system error. 
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error 8013: 


The file specified could not be opened. 
This is an 
internal system error. 


error 8014: 


There were an incorrect number of arguments on the 
operating system command line. 
One argument is ex- 
pected. 


error 8015: 


An open comment symbol, 
{, was found inside an al- 
ready open comment on the specified line, at the 
specified character position. 
This could be due to 
a failure to close the previously opened comment, 
which was begun on the specified line at the speci- 
fied character position. 


error 8016: 


A comment has been opened, but not closed. 
The last 
comment begun was opened on the specified line at 
the specified character position. 


error 8011: 


An illegal (invisible, control) character has been 
found on the specified line at the specified charac- 
ter position. 
It has been replaced by a blank in 
the listing, but it is still in the source (input) 
file, and should be removed before attempting to 
compile again. 


error 8018: 


A grammatical error has been found on the specified 
line at the specified character position. 
The con- 
struct is not understandable in its context. 


error 8019: 


This integer exceeds the maximum size allowed. 
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error 8020: 


The file specified could not be opened. 
The 
operat~ 


ing system was asked to open it for reading. 


error 8022: 


This identifier exceeds the maximum length for iden- 
tifiers. 


error 8023: 


This quoted string exceeds the maximum length for 
quoted strings. 


error 8024: 


An unbalanced quote has been found on the specified 
line at the specified character position. 
Any 
printable character may be used in a quoted string. 
but the quotes must be opened and closed on the same 
line. 


error 8025: 


The comment close symbol. 
}. has been found on the 
specified line at the specified character position. 
even though no comment has been opened. 


error 8027: 


An illegal (invisible. control) character has been 
found on the specified line at the specified charac- 
ter position. 
It has been replaced by a blank in 
the listing. but it is still in the source (input) 
file. and it should be removed before attempting to 
compile again. 


error 8030: 


A typographical error has been found on the speci- 
fied line at the specified character position. 
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error 8031: 


An internal system error has occurred. 


error 8045: 


UNIQUE fields may only be specified when creating a 
temporary file. 


error 8050: 
. 
The file specified could not be created. 


error 8051: 


The LEFT MARGIN must be no less than zero and no 
greater than the RIGHT MARGIN. 


error 8053: 


Neither the PAGE LENGTH, TOP MARGIN, nor BOTTOM MAR- 
GIN are allowed to be less than zero. 


error 8054: 


The string specified does not fit into remaining 
space in the compiler's string table. 


error 8055: 


This double causes the double table in ACEPREP to 
overflow. 
Save space in the double table by using 
integer constants instead of floating point con- 
stants where possible. 


error 8056: 


Skipping lines inside of WHILE or FOR loops is not 
allowed within PAGE HEADERS or TRAILERS. 


error 8057: 


Only user variables of type CHARACTER may be sub- 
scripted or have lists in the LET statement. 
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error 8059: 


The limit for IF statement nesting has been exceed- 
ed. 
There are too many IF statements within IF 
statements for ACE to properly compile this specifi- 
cation. 


error 8060: 


The last READ statement cannot be a LET statement or 
an ALIAS statement or an optimized READ of aggre- 
gates. 


error 8061: 


The name specified is not suitable for a temporary 
file name or alias name because it has been declared 
as a variable name. 


error 8062: 


The name specified cannot be a field name in a file 
because it is a declared variable name. 


error 8102: 


There may be only one AFTER or BEFORE GROUP OF 
clause for any single field specified in the SORT 
command. 


error 8103: 


In order for the BEFORE or AFTER GROUP OF clause to 
function properly, the field specified in the clause 
must also have been specified as a sort field in the - 
SORT command. 
If the sort field is subscripted, so 
too must be the field in the BEFORE or AFTER GROUP 
OF clause. 


error 8104: 


Group aggregates can only be used in an AFTER GROUP 
OF clause. 
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error 8105: 


Aggregates may not be used within another aggregate. 
Nor may aggregates be used within the WHERE clause 
ot another aggregate. 


error 8106: 


The expression in the WHERE clause in the above READ 
statement is too large to be properly parsed by ACE. 


error 8101: 


A user variable or parameter has been defined by the 
user more than once. 


error 8108: 


A user variable or parameter must have a length 
which is greater than zero. 


error 8110: 


The user variable specified has not yet been defined 
by the user. 


error 8111: 


User variables and run-time parameters may not be 
used in a SORT statement. 


error 8112: 


Within an IF-THEN-ELSE statement of a header or 
trailer clause, the number of lines printed in the 
IF part must equal the number of lines printed in 
the ELSE part. 


error 8113: 


SKIP TO TOP OF PAGE is not allowed in any header or 
trailer clause. 
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error 8114: 


The number of lines to be printed in the top and 
bottom margins plus the lines to be printed in the 
page header and trailer clauses exceed the page 
length. 


error 811;: 


There may be no more than eight sort fields speci- 
fied in the SORT command. 


error 8116: 


Illegal subscripting in SORT command. 


error 8117: 


ACEPREP has run out of storage for expression nodes. 


error 8118: 


ACEPREP has run out of storage for values. 


error 8119: 


The READ statement has exceeded the maximum number 
of JOINS between files. 


error 8120: 


ACEPREP has run out of storage for attribute 
descriptors. 


error 8121: 


The READ statement has exceeded the maximum number 
of temporary fields. 


error 8122: 


A NEED LINES statement may not be used in PAGE 
HEADER or PAGE TRAILER clauses. 
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error 8123: 


The PRINT FILE command is not allowed within the 
FIRST PAGE HEADER, 
PAGE HEADER, or PAGE TRAILER 
clauses. 
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error 9001: 


Only fields of type CHARACTER may be subscripted or 
printed without trailing blanks. 


error 9002: 


An unknown operation code was found in the PMIM 
(Pseudo-Machine Instruction Memory). 


error 9004: 


The fie Id specified is not in the current file. 


error 9009: 


A sort cannot be done using the optimized read 
feature of ACE unless an index has already been 
created for the sort field using DBSTATUS. 
If a 
hierarchical sort on two or more fields is desired, 
reading into a temporary file will solve the prob- 
lem. 


error 9010: 


The field specified could not be found. 


error 9011: 


The file specified could not be 
found~ 


error 9014: 


An ACE report program name must be specified as the 
first argument on the command line. 


error 9015: 


The database specified could not be found. 


INFORMIX 
163 


ACE Relational Report Writer 


error 9023: 


Unable to add index for a sort key. 


error 9024: 


'There is no data in the file specified. 


error 9025: 


The field specified is not in the current file. 
All 
fields used as a SORT field must be in the current 
file. 


error 9029: 


The temporary file specified either could not be 
opened or created. 


error 9030: 


The temporary file specified could not be recon- 
structed. 


error 9031: 


The field specified could not be found in the desig- 
nated file. 


error 9032: 


The corresponding fields in a JOIN clause of a READ 
command must be of the same type and length. 


error 9040: 


The two temporary files involved in SET operations 
must be union compatible. 
They must contain the 
same number of fields. 
Each field must be of the 
same type and length as its counterpart in.the other 
file. 
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error 9042: 


Each temporary file name used in an ASSIGN statement 
must be unique. 


error 9046: 


. Too many UNIQUE fields were specified in this READ 
command. 
The maximum number of fields is 8. 


error 9047: 


The output file specified could not be created. 


error 9048: 


No more than 200 fields may be included in a tem- 
porary file. 


error 9049: 


A value entered by the user as a command line param- 
eter cannot be converted to the data type specified. 


error 9050: 


The value entered by the user cannot be converted to 
the type of variable indicated. 


error 9051: 


The number of defined-parameters in the ACE program 
does not equal the number of actual parameters 
passed to ACEGO on the command line. 


error 9054: 


A version incompatibility has been detected. 
Recom- 
pile your ACE report specification using ACEPREP and 
then re-run ACEGO. 
Be certain that the version 
numbers for ACEPREP and ACEGO are identical. 
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error 9055: 


A Pseudo Machine Stack error has occurred within 
ACE. 
A type pushed on the stack is not recognized 
by ACE. 
This is an internal error. 


error 9060: 


The values used to subscript the field are outside 
the bounds for the field's defined length. 


error 9062: 


An error has occurred during the conversion of an 
INTEGER or DOUBLE to a CHARACTER type user variable 
or database field. 
The CHARACTER type field is not 
long enough to hold the result. 


error "9063: 


The user function specified, defined by the user in 
the DEFINE statement of ACE, could not be found in 
the C function definition table "userfuncs" in the 
user's C static data area. 


error 9064: 


The run-time string table is full. 


error 9065: 


Memory allocation has failed. 
The user's ACE report 
specification is too large. 


error 9066: 


An error has occurred while writing to the output 
report. 


error 9067: 


ACE's arithmetic stack has exceeded its bounds. 
The 
expression here is too complicated. 
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error 9069: 


Wildcard matching cannot be done on non-character 
fields. 


error 9080: 


The field specified does not exist in the temporary 
file specified. 


error 9081: 


A memory allocation error has occurred. 


error 9082: 


The query has exceeded the maximum number of files. 


error 9083: 


The query has exceeded the maximum number of joins. 


error 9084: 


The query has no joins but references more than one 
file. 


error 9085: 


There are too many joins in the query. 
There is 
probably a circular join in the query. 


error 9086: 


There are not enough joins among the referenced 
files in the query. 


error 9087: 


The file specified does not appear in the join list. 
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error 9088: 


A join path does not exist between all the refer- 
enced file s • 


error 9091: 


The file specified is not a temporary file. 


error 9093: 


The query has exceeded the expression storage space. 


error 9094: 


The query has exceeded the constant storage space. 


error 9098: 


A unique id could not be created for a new record. 


error 9102: 


Character fields cannot be compared with non- 
character constants. 


error 9103: 


Character fields cannot be assigned non-character 
values. 


error 9105: 


The database file specified could not be opened. 


error 9110: 


An index could not be added for set operation result 
file. 
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error 9111: 


An isstart could not be done for set operation 
result file. 


error 9112: 


The name specified cannot be used as a temporary 
file name. 
It is already the name of a permanent 
file or field. 


error 9113: 


A temporary name can be assigned only to a permanent 
file or an actual temporary file (not another 
alias). 
A temporary name cannot be used to re-name 
a temporary file of the same name. 


error 9117: 


Totals and averages cannot be computed for character 
fields. 


error 9119: 


In an optimized sort, all the sort fields must come 
from one existing file. 


error 9122: 


Operations cannot be done on the composite field 
specified. 


error 9123: 


Permission is not granted to use the field speci- 
fied. 


error 9127: 


Permission is not granted to read any of the output 
fields. 


..-.. 
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error 9133: 


Permission not granted to use a member field of the 
composite field specified. 


error 9498: 


An ASCII to date conversion error has occurred. 


error 9499: 


An ASCII to binary conversion error has occurred. 


error 9501: 


The file specified could not be opened to read out- 
put tuples. 


error 9502: 
Isstart could not be done on sortkey for tuple out- 
put. 


error 9503= 


The file specified could not be opened. 


error 9504: 


The composite field indicated cannot be specified in 
a PRINT statement. 
The PRINT statement must specify 
the individual member fields. 


error 9505: 


Sorting cannot be done on the composite field speci- 
fied. 
The SORT statement must list the individual 
tields. 
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I. 
Introduction 


INFORMER is an interactive query language for 
INFORMIX. 
Because of INFORMER's ease of use and 
simplicity, data-processing professionals and non- 
professionals alike can query an INFORMIX database 
easily and effectively. 
INFORMER is a non- 
procedural language. 


INFORMER allows the user to examine a database 
file or specific parts of a file. 
You can also for- 
mulate queries that involve more than one file. 


In the relational model, relationships between 
data files are determined at the time of data re- 
trieval, rather than at the time of file creation. 
If two files have fields that relate them, queries 
can be formulated to take advantage of that rela- 
tionship. 
The flexibility and power of data re- 
trieval with INFORMER are limited only by the imagi- 
nation of its users. 


The rest of this document consists of an expla- 
nation of INFORMER's syntax and illustrations of 
INFORMER's capabilities through examples. 


The following databases are used for the first 
several examples in this chapter. 
They are the 
demonstration databases distributed with INFORMIX. 
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The stores Database 


database stores 
file customers 
permission all 


field cname 
type char 15 
field address 
type char 15 
field balance 
type double 
file orders 
permission all 


field oname 
type char 15 
field item 
type char 15 
field quantity 
type integer 


The realty Database 


database realty 
file agents 
permission all 


field agent_number 
type integer 
field agent name 
type char 15 
field agent-address 
type char 20 
field agent-city 
type char 10 
field agent-zip code 
type long 
field agentyhone 
type char 8 
field agent_salary 
type money 


file listings 
permission all 


field Iisting_number 
type integer 
field address 
type char 20 
field city 
type char 20 
field footage 
type integer 
field bedrooms 
type integer 
field baths 
type integer 
field lot size 
type double 
field corner lot 
type char 1 
field schools 
type char 1 
field asking price 
type money 
field salesyrice 
type money 
field broker 
type char 15 
field Iisting_note1 
type char 45 


... J:I' 
: 
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II. 
Syntax and Structure 


II.A. 
Syntax 


INFORMER uses the field and file names you de- 
fined with the DBBUILD data description language. 
Files created with DBBUILD are permanent database 
files. 
You may create temporary database files dur- 
ing the course of an INFORMER session. 
File names 
for temporary files must begin with a letter and can 
be up to 50 characters long. 
However, only the 
first 10 characters (in UNIX systems) and only the 
first 8 characters (for MS-DOS systems) will be used 
to determine uniqueness. 
Use only the characters 
A-Z, 0-9, and underscore ( ) for filenames. 
Upper- 
and lowercase are not signIficant in file names. 
Temporary database files for query results may con- 
tain up to 200 fields, but anyone record may not be 
longer than 2048 bytes. 
Temporary files may be used 
more than once during a session. 


Temporary database files can be printed and 
used in other queries, just as if they were per- 
manent files. 
When you exit from INFORMER, tem- 
porary files are erased. 
If desired, the informa- 
tion in these temporary files can be saved using the 
UNLOAD command. 
UNLOAD creates an operating system 
file containing the data. 


Unloaded data can be loaded into a permanent 
database file using the LOAD command of DBSTATUS 
(discussed in the DBSTATUS Chapter.) 
This feature 
allows INFORMER to be used to alter the structure of 
files, or to put a subset of the records of a file 
into a new file. 


By using a combination of INFORMER, DBSTATUS, 
and DBBUILD with the rebuild option, two or more 
files can be permanently merged, or one file can be 
made into more than one permanent database file. 
The schemas for all newly created permanent database 
files must be added to the data dictionary using 
DBBUILD before you load the data. 
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II.B. 
Multi-line Commands 


All INFORMER commands are terminated with a 
semicolon (j) or, optionally, with the word end. 
Certain commands -- HELP, BYE, 
EXECUTE, and RUN -- 
do not require this terminator. 


INFORMER commands may continue for more than 
one line. 
As many lines as needed may be used for 
commands. 
The command line breaks in the examples 
in this chapter are arbitrary. 


The INFORMER prompt is the ">" character. 
The 
second and subsequent lines of a command are prompt- 
ed for with the "»" sequence. 
Commands that re- 
quire a terminator are not sent to the program until 
the semicolon (j) is typed, followed by a RETURN. 
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III. 
Hov To Run INFORMER 


Run INFORMER by selecting option 3 on the Mas- 
ter Menu. 
When a current database has been 
established, 
INFORMER is ready for commands. 


You can also run INFORMER directly from the 
operating system. 
INFORMER prompts for the database 
name. 
You may then either enter a database name, or 
type b (for ~) to exit from the program. 


Here is an example of running INFORMER from the 
operating system: 


"informer 
. 


INFORMER Relational Query Language 
INFORMIX version 3.2 
Copyright (C) 1981, 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-000001 


Type help for sample commands. 


Please enter the database you would like to select. 
> stores 


Database "stores" has been selected successfully. 


The database can also be selected from the com- 
mand line, as shown below: 


% informer stores 


You can also run a prepared query file from the 
command line. 
In the example below query1 is a file 
containing a sequence of INFORMER commands. 
More 
information can be found in the section on the EXE- 
CUTE command. 


% informer stores query1 


After selecting a' database, you can use any of 
the commands discussed in this chapter. 
A command 
may be terminated prematurely by pressing the DELETE 
(on some terminals, 
RUBOUT) key. 
INFORMER only 
alters the database when the ADD, 
DELETE, or UPDATE 
commands are used. 
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To select another database without leaving the 
INFORMER program, use the SELECT DATABASE command. 
The syntax for the command is: 


SELECT DATABASE databasename 


No terminator (except for the usual RETURN) is 
required for the SELECT DATABASE command. 


Finally, if you want to suppress INFORMER sys- 
tem messages, use the "quiet" flag (-q): 


% informer -q stores 


III.A. 
Leaving INFORMER 


You leave INFORMER with the BYE command. 
The 
BYE command closes all files opened during the ses- 
sion, removes all temporary files and ends the IN- 
FORMER session. 
Execute the BYE command by entering 
the word bye or just b followed by RETURN. 


> bye 
Program over. 


III.B. 
PRINT 


As a relational database management system, 
IN- 
FORMIX provides the "select," "project," and "join" 
operations. 
A selection creates a new group of 
records by taking all records from the existing set 
which satisfy some condition. 
A projection speci- 
fies which fields are to be displayed from the group 
of records. 
The join operation creates new records 


by connecting records on fields that have some 
identical values. 
INFORMER incorporates the select, 
project, and join operations into two 
commands~ 


PRINT and READ. 


Here is a PRINT command that prints all of the 
customers from the customers file who have a balance 
of zero. 
The command includes a WHERE clause that 
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specifies the selection operation. 
This PRINT com- 
mand also demonstrates the projection operation, 
since only the cname and balance fields are listed 
for printing. 
No spaces are needed before the ter- 
minator (;). 


> print cname balance where balance 
0; 


cname 


Field, 
W. 


Court, S. 
English, D. 


balance 


0.00 
0.00 
0.00 


Another example of the PRINT command with a 
WHERE clause selects all of the customers that have 
either a zero balance or owe less than 20 dollars: 


> print 
» 
cname balance 
» 
where balance 
»; 


cname 


Field, W. 
Court, S. 
English, D. 
Brooks, B. 


0.00 or balance <= 20.00 


balance 


0.00 
0.00 
0.00 
10.50 


This command was typed on more than one line. 
Since INFORMER is a free format language, lines can 
be broken with,a RETURN at any point. 


Since every field name in a database is unique, 
you do not have to name the database file in an IN- 
FORMER query in order for the program to know which 
fields you 
w~nt. 
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111.B.1. 
The Relational Operators 


There are two main types of operators for use 
in WHERE clauses: the relational operators and the 
logical (Boolean) operators. 
INFORMER supports the 
logical operators AND, OR, and NOT, and seven rela- 
tional operators that are used to qualify fields for 
selection. 
The relational operators are discussed 
first. 


Relational Operators 


=<> 
<= 
>= 
<> 
matches 


Equal to 
Less than 
Greater than 
Less than or equal to 
Greater than or equal to 
Not equal to 
Matches a pattern 


(for use with wildcard characters) 


The first six relational operators are used to 


qualify field values specified for selection, or to 
compare two fields. 


For searches with the relational operators in 
character fields, numbers are < (earlier in the al- 
phabet) than CAPITAL letters, and CAPITAL (upper- 
case) letters are < lowercase letters. 


When selecting on a CHARACTER or DATE field, 


surround the specified value With double quotation 
marks: "". 
No error message is generated if you do 
not surround a date with double quotation marks for 
a search, but the results will be incorrect. 


If the quoted string is shorter than the field 
to which it is being compared, 
INFORMER will select 
records using the shorter string. 


> print cname balance where cname = "Eng" 


cname 


English, D. 


balance 


0.00 


You can compare two fields with the relational 
operators: 
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print listing_number where baths> bedrooms ; 


This query to the realty database prints listing 
numbers of houses having more bathrooms than bed- 
rooms. 


Selection values for numeric fields (integer, 
long, double, serial, float, money) need ~ be·sur- 
rounded by double quotation marks. 


111.8.2. 
Selections with Wildcard Characters 
and the MATCHES Operator 


When more flexibility in string searches is re- 
quired than is provided by the equal sign (=) and 
the other relational operators, use the MATCHES re- 
lational operator. 


While the equal sign (=) instructs INFORMER to 
find records in which the quoted string is identical 
to (all or the first part of) the field, 
MATCHES al- 
lows you to perform wildcard searches. 
If you try to use Wildcard characters with the 
relational operators, no error message is generated, 
but the search will fail. 


The MATCHES operator is used only for searches 
in character fields. 


Here is a set of examples of use of the wild- 
card characters: 


If you are seeking "Lewis" but you suspect that 
this name might be spelled "Louis," you could use 
the MATCHES operator with wildcards to search for 
both spellings. 


I 


The wildcard characters include the question 
mark (?), which means "match anyone character," and 
the asterisk (*), which means "match any number of 
characters." The following two examples use wild- 
cards to print all records containing LewJs or 
Louis. 
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print cust num, cust name 
where cust_name matches "L??is"; 


print cust num, cust name 
where cust_name matches "L*is"; 


Here are some additional examples from the 
stores database file: 


> print cname where cname 
"Ro" 


cname 


Robin, R. 


> print cname where cname matches "R??in*" 


cname 


Robin, R. 


> print cname where cname matches "R*in*" 


cname 


Robin, R. 


These examples differ in the number of charac- 
ters being matched. 
Examples with? match one char- 
acter for each question mark. 
The earlier example 
(L??is) prints only records with five character 
names, Lewis, Louis, Loois, Lokis, etc. 
Since the 
asterisk matches "anything", the second example 
(L*is) prints Lis, Lois, Lewis, Louis, Lokis, La- 
voris, etc. 
The only requirement for a match in 
this case is that the first letter is "L" and the 
last letters are "is". 


MATCHES, unlike "=", will not print out records 
which continue beyond the end of the quoted string. 
Therefore, In the two examples just explained, names 
like Lewiston and Lewister will not be printed. 
Ei- 
ther use "=" and the first part of the string, or 
use an asterisk at the end to cause INFORMER to 
search to the end of the string. 


print cust num, cust name 
where cust_name matches "Lewis*"; 
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Additional wildcard characters are brackets 
«(]), meaning "match anyone of the characters in- 
side the brackets," and brackets containing a caret 
as the first character ([ A]), meaning "match any 
character that is NOT inside the brackets." 


Here is a summary chart of the INFORMER wild- 
card characte r s: 


Wildcard Characters 


? 
replaces any single character 
* 
replaces 0 or more characters 
[) 
encloses a class of characters to select 


[AJ 
encloses a class of characters to exclude 


Wildcard characters may combine and repeat in a 
pattern. 
They can appear at any position in a 
search pattern. 


The square brackets are used to surround a 
class of characters to be matched: 


(xy) 


(A xy ) 


[x-z} 


(AX-ZJ 


matches anyone of the characters 
inside the brackets 
matches any character NOT inside 
the brackets 
matches any character in the range 
from x-z, inclusive 
matches any character NOT in the 
range from x-z, inclusive 


The * accompanies a character class when you need to 
search to the end of a string, or to replace any 
number of characters in the string. 


The following examples from the listings file 
of the realty database show the use of character 
classes. 
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> print city asking_price where city matches "[HM]*"; 


A sequential search will be used 
to satisfy the WHERE clause. 


city 


Madison 
Hargrove 
Madison 
Madison 


150000.00 
150000.00 
176000.00 
140000.00 


> print city asking price 
» 
where city matches "[H-M]*"; 


A sequential search will be used 
to satisfy the WHERE clause. 


city 


Madison 
Hargrove 
Madison 
Madison 


> 
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150000.00 
150000.00 
176000.00 
140000.00 
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> print city asking price 
» 
where city matches "[H-M](ar]*"; 


A sequential search will be used 
to satisfy the WHERE clause. 


city 


Madison 
Hargrove 
Madison 
Madison 


150000.00 
150000.00 
176000.00 
140000.00 


> print city asking price 
» 
where city matches "[ "HMJ*"; 


A sequential search will be used 
to satisfy the WHERE clause. 


city 


Santa Clara 
Sunnyvale 
Buck Creek 
Santa Clara 


189000.00 
169000.00 
145000.00 
205000.00 


The first three examples yield identical 
results. 
The first two select records where the 
city name begins with H or H, 
and the third case 
prints records where the first character is H or M 
and the second character is a or r. 
The last exam- 
ple selects records where the first character is not 
H or M and where the second and sUbsequent charac- 
ters can be anything. 


Wildcards can be used at any position in a 
quoted string, and they may be repeated as desired. 
If you want to search for a wildcard character as 
such, precede the character with a backslash (\) in 
the quoted string. 
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111.8.3. 
Searching for Null or Default Values 


When you want to search for fields in which no 
entry has been made, 
you must specify that the 
search is to include "null values." Empty fields may 
have a default value put in by INFORMER automatical- 
ly. 
The selection value for no entry in a character 
field is an explicit blank in double quotation 
marks: 


where p_lname 
= 


For a number field, specify the search cri- 
terion as 0: 


where p-project = 0 ; 


You use 0 to search for blank entries in number 
fields because 0 is the default entry for a number 
field. 
Likewise, use "00/00/00" to search for blank 
date fields. 
Use the standard default entry for the 
particular type of field. 


111.8.4 
The Logical Operators 


The logical (Boolean) operators that INFORMER 
prOVides are AND, OR, and NOT. 
Logical operators 
extend the power of the INFORMER query language by 
permitting you to combine many selection criteria in 
one query. 


The AND operator combines selection criteria. 
A record must satisfy both criteria in order to be 
selected. 
You use AND by inserting the AND operator 
between criteria in the WHERE clause: 


> print cname 
» 
where cname = "Eng" and balance >= 0 


The 
OR operator finds records that meo.t anyone 
of two or more criteria: 


> print cname where 
» 
cname - "Eng" or 
» 
balance >- 0 or cname matches "R??in"; 


Use the 
NOT operator in combination with the 
AND and OR operators to exclude records from a 
selection. 
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> print cname where 
» 
balance >= 0 and not balance = 10.50 ; 


The NOT immediately precedes the field name it 
affects. 
String together additional 
NOT phrases 
with ANDs and DRs as desired. 


The relational not equal to «» 
operator can 
replace the logical NOT operator when wildcard char- 
acters are not used in the selection pattern. 


If an INFORMER logical expression has an AND 
operator and an OR operator, the 
AND operation will 
be performed first. 
The AND operations take pre- 
cedence over the OR operations. 
Parentheses may be 
used to enforce or to override this default pre- 
cedence. 


III.B.5. 
Printing Entire Files 


Use file names instead of a list of fields to 
print all of the fields in the file. 
The PRINT com- 
mand can print up to 200 fields from a permanent or 
temporary file. 


Field values are printed in columns beneath the 
field names. 
If the records are too wide to fit on 
a standard 80-column terminal screen, field names 
and values are printed down the screen instead of 
across. 


> print customers ; 


cname 


Brooks, B. 
Field, 
W. 


Robin, R. 
Hart, 
W. 
Court, S. 
English, D. 


address 


7 Apple Rd. 
43 Cherry Ln. 
12 Heather Ct. 
65 Lark Rd. 
56 Blossom Rd. 
82 Alpine Rd. 


balance 


10.50 
0.00 
23.45 
43.00 
0.00 
0.00 


The PRINT command need not select or join, but 
may just project, as shown below. 
A projection 
alone prints every record, but projects only speci- 
fied fields. 
The command below also shows the op- 
tional separation of the field names in a list by 
the word AND. 
Field or file names in a field list 
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may be separated by AND, a comma, or blanks. 


> print item and oname 


item 


Work Bench 
Saw 
Work Bench 
File 
Hammer 
Saw 
File 
File 
Hammer 


oname 


Brooks, B. 
Brooks, B. 
Robin, R. 
Hart, 
W. 


Robin, R. 
Court, S. 
Court, S. 
English, 
D. 
English, 
D. 


III.C. 
JOINING and UNIQUE 


A join uses the PRINT command or the READ com- 
mand with a field name list and a JOINING clause. 


The use of a WHERE clause is optional. 
A WHERE 
clause can precede or follow a JOINING clause. 


A JOINING clause contains the command word 
JOINING and the join field names shown as equal to 
each other. 
Here is a syntax diagram for JOINING: 


print {file(s) } [WHERE ••• ] JOINING field A = field B 


{field(s)} 


Simultaneously with the JOINING operation, you 
select or project any or all of the fields from any 
or all of the files participating in the join. 


A single JOINING command can combine data from 


several files, 
depending on the limits of your 
operating system. 


If you try to print fields from more than one 
file without requesting a join, you get an error 
message: 
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> print personnel, projects 
» 
where p_project 
= pr_num 


The query has no joins but references more 
than one file. 
See error number 7084. 


The fields you name for a JOINING will have 
different names, as required by INFORMIX data 
definition rules. 
However, the JOINING fields must 
be functionally identical -- of the same type and 
the sam.e length. 


A serial field cannot be joined to another 
serial field. 
Joining serial fields is accomplished 
by changing the serial field in one of the files to 
type long (by editing the schema) and then rebuild- 
ing the database using DBBUILD with the -r option. 


No JOINING can take place unless the join 
fields contain some values that are identical. 


Use JOINING to combine information from more 
than one file. 
For example, customers with a bal- 
ance of less than $20.00 might be considered good 
credit risks. 
The store manager would like to keep 
the goods ordered by these customers in stock, to 
help reduce his accounts receivables. 
To obtain a 
list of all the items currently on order by people 
who keep a low balance, a query could be constructed 
JOINING the two files using the customer names, and 
printing the items from the orders database file. 
The following command accomplishes this. 


> print item joining cname = oname 
» 
where balance <= 20.00 ; 


item 


Saw 
File 
File 
Hammer 
Work Bench 
Saw 


When a PRINT command contains a JOINING clause, 
all of the fields in the field list must be from ei- 
ther of 
th~ two files involved in the JOINING. 
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Duplicates may appear in a JOINING result as a 
natural consequence of the query. 
Duplicates can be 
eliminated using a READ command with the UNIQUE key- 
word, followed by a PRINT command. 
In a list of 
fields, 
UNIQUE is applied to the fields it immedi- 
ately precedes. 
UNIQUE can only be used with the 
READ command, which creates a temporary file. 
The 


temporary file is then printed to display the 
results: 


> read into unitem 
» 
unique item joining cname = oname 
» 
where balance 
<= 20.00; 


> print unitem ; 


item 


Saw 
File 
Hammer 
Work Bench 


UNIQUE can be used on more than one field: 


> read into uname 
» 
unique cname item joining cname 
» 
where balance <= 20.00 ; 


> print uname ; 


oname 


cname 


Court, S. 
English, 
D. 
Brooks, B. 


item 


Saw 
File 
Work Bench 


Records are not printed in sorted order unless 
the SORT command is used (see Section V.B.). 
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111.0. 
Saving Query Results 


You can use the PRINT TO "filename" command to 
send output to a standard operating system file. 
The WITHOUT HEADINGS clause of this command may be 
used to suppress the printing of the field names, if 
desired. 
One use of this PRINT option is to gen- 
erate simple reports by using INFORMER to select 
data of interest and print it to a file. 
The file 
can then be viewed, edited, or sent to the printer, 
using the appropriate operating system commands. 


> print oname item to "projectout" ; 


or 
> print oname item to "projectout" 
» 
without headings; 


Users of INFORMER with the UNIX operating sys- 
tem can send a report to the "standard input" of 
another program, instead of to a disk file. 
A typi- 
cal use for this facility would be to send a query 
result directly to the line printer, as follows: 


> print oname item to pipe "lpr" ; 


(Piping to "lpr" works only if you have a function- 
ing spooler program.) 


The WITHOUT HEADINGS clause can be used with 
either the TO "filename" or TO PIPE "programname" 
clause. 
These Clauses, plus the WHERE and JOINING 
clauses, may be used in any order. 


III.E. 
Printing Database Schema and Status 


To see the schema for a database, or to print 
the status of the database, use one of the following 
commands: 


> print schema 
> print 
schema 
> print status 
> print status 
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III.F. 
The PRINT Command 


The foregoing brief discussion was intended to 
give some feeling for the structure of the PRINT 
command, and how it can be used to perform selec- 
tions, projections and joins. 
A more detailed syn- 
tax for the PRINT command follows: 


> PRINT fieldlist 


{WITHOUT HEADINGS 
} 
{TO "filename" 
} 
{TO PIPE "prog:-amname"} 
{WHEREclause 
} 
{JOININGclause 
} 


where zero or more of the five choices in the curly 
brackets can be used in any order, and where 


fieldlist = 


JOININGclause 


WHEREciause 
= 


one or more field names or file 
names separated by commas, 
blanks or the word "and" 


the keyword JOINING followed by 
field = field or 
field = OPTIONAL field 


the keyword WHERE followed by a 
logical-expression 


logical-expression 
field relop constant 
or 
logical-expression 
logop 
logical-expression 


where a relop is one of the relational operators 


<> 
< 
> 
<= 
>= 
MATCHES 


and logop is one of the logical operators 
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III.G. 
The READ Command 


The READ command creates temporary database 
files you can print or use in subsequent READ or 
PRINT statements. 
For example, the PRINT statement 
shown below could be broken into the two READ state- 
ments also shown, and the intermediate results would 
still be available for examination for the remainder 
of the INFORMER session. 


Fields in temporary files may be addressed by 
prefixing the field name with the name of the tem- 
porary file followed by a period (e.g., 
tempfile.field). 


> print cname oname item where balance = 0 
» 
joining cname = oname; 


> read into x cname balance where balance = 0; 


> print x; 


cname 


Field, 
W. 
Court, S. 
English, D. 


balance 


0.00 
0.00 
0.00 


> read into y x.cname oname item 
» 
joining x.cname = oname; 


> print y; 


cname 


Court, S. 
Court, S. 
English, D. 
English, D. 


oname 


Court, S. 
Court, S. 
English, 
D. 
English, 
D. 


item 


Saw 
File 
File 
Hammer 


A READ command uses all of the PRINT command 
syntax, except for WITHOUT HEADINGS, 
TO "filename", 
and TO PIPE "programname". 
A temporary database 
file may be assigned any name beginning with a 
letter. 
Names may be re-used. 
Temporary database 
files are erased by INFORMER when you exit from the 
program at the end of the session. 
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III.H. 
The UNLOAD Command 


Temporary database files created with READ can 
be written to operating system files using the UN- 
LOAD command. 
(You can also unload permanent files 
with the UNLOAD command.) 


The syntax of the UNLOAD command is: 


> UNLOAD tmp TO "filename" ; 


where tmp is any temporary database file name, and 
filename is the name of the operating system file 
that is to hold the unloaded form of the temporary 
database file. 


UNLOAD prepares data for loading into new data- 
base files, to create new database files from data 
derived from other parts of the database. 


> unload 
~name balance to "hold" ; 


Alternatively, you can perform the selection 
with UNLOAD instead of creating a temporary file 
with READ. 


The syntax for using a WHERE clause or JOINING 
clause with UNLOAD is: 


UNLOAD fieldname-list {WHERE-clause 
} TO "filename"; 
{JOINING-clause} 


However, since selections may not succeed on 
the first attempt, it is preferable to use READ and 
a temporary file, then UNLOAD the file once it con- 
tains the'desired selection. 


III.H.1. 
Creating Permanent Database Files 


You can transform the temporary result files 
READ creates into permanent data files using the 
commands UNLOAD, DBBUILD, and LOAD. 


The UNLOAD command puts the files into a spe- 
cial format that the LOAD command can use to create 
a new database file. 


By default, a file in UNLOAD format is to be 


(. 
\ 
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used only by the LOAD program. 
special characters that make it 
ination with an editor or other 
utility. 


However, the UNLOAD ASCII version of the 
UNLOAD 
command 


UNLOAD ASCII tempfile to "filename" 
; 


creates an unloaded file that contains only ASCII 
characters. 
You can use any operating systems pro- 
gram (editor, file transfer program) on a file 
created with UNLOAD ASCII. 


The DELIMITER command may be used to change the 
default delimiter character that sets off database 
fields in the file created by the 
UNLOAD ASCII com- 
mand. 
The DELIMITER command must be used prior to 
UNLOAD ASCII. 
For example, if you wanted the delim- 
iter in your ASCII-unloaded file to be an exclama- 
tion point, you would use the following: 


delimiter "!" ; 
unload ascii tempfile to "filename" 


To create a permanent database file from a tem- 
porary file, 
you first bUild a schema for the new 
file with DBBUILD and then LOAD the data into it 
from the file. 
You can also load data into an ex- 
isting database. 
LOAD appends to the existing data. 


Unloading data from a temporary result file 
does not destroy the original data, but makes a copy 
of it that you can load into a new schema. 


After unloading the selection to a file, build 
a new schema containing the same field definitions 
as the fields that READ places in the temporary 
result file. 
The fields in the new schema must also 
appear in the same order as those in the result 
file. 


Where a join exists, you will need to include 
the relevant field definitions from all of the files 
that participated in the join. 
-- 
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IILH.2. 
Hints for Creating a 
New Schema 


An easy way to create a new schema is to edit a 
~ of the schema file that defines the first field 
of the result file you want to make permanent. 


Append (read in) copies of other schema files 
to this file as required. 
Then, one by one, delete 
field definitions that are not in the file you plan 
to load using the new schema. 


Now that the relevant fields appear in the new 
schema file under their original names and defini- 
tions, 
some important modifications must be made. 
These include: 


• 
Changing the database name, 
OR 


• 
Changing every field name 


• 
Removing indexes 


• 
Changing serial data type fields to another 
type, such as "long" 


If you change the database name on the first 
line of the schema, the field names can remain the 
same. 


On the other hand, if you want the new database 
file you are bUilding to be in the same database as 
the file(s) from which it was derived, you must 
change every field name in the new schema in order 
to satisfy the INFORMIX requirement of unique field 
names within a database. 


The file name you choose for the new data file 
should not be the same as the file into which you 
unloaded the query results. _ As a convention, you 
could unload the temporary file to a file name with 
a designated suffix, such as .unl (filename.unl), 
and name the file in the new schema with the root 
name (filename), making sure that you do not use an 
existing file name. 
Only the first ten characters 
of a file name (for UNIX systems) or the first eight 
(for MS-DOS systems) are used to test for the 
uniqueness of a file name. 


Next, delete INDEX keywords from field defini- 
tions. 
Indexes can be added after you load the 'new 
database file. 
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Finally, change any fields of type SERIAL to 
type LONG, and remove the PRIMARY KEY keyword wher- 
ever it occurs. 


III.H.3. 
Loading the New Schema 


When you finish bUilding the schema, compile it 
with DBBUILDas usual. 
Once it compiles successful- 
ly, you can load data into it. 


Load data with the LOAD command of the DBSTATDS 
program. 
The LOAD syntax is: 


LOAD filename FROM "filename. unl" 


111.1. 
The ASSIGN Command 


The ASSIGN command and its UNION, 
MINUS and 
INTERSECT clauses allow the user to perform basic 
set operations. 
You can create.a union, intersec- 
tion or difference of two temporary files. 
First 
create the temporary files with READ, and then use. 
one of the following: 


> ASSIGN c = a UNION b 


or 


> ASSIGN d 


or 


a INTERSECT b 


> ASSIGN e = a MINUS b ; 


To perform set operations the two files must be 
"union-compatible." They must have fields of the 
same type and length, and in the same order. 
The 
file specified on the left-hand side of the set 
operator determines the field names of the new file. 
The examples below initially create two temporary 
files from one database file for the purpose of 
demonstrating the operation of ASSIGN. 
The fields 
in these examples were therefore completely union- 
compatible, since they came from the same file. 
When the fields come from different files, the 
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fields in the result file, for example c, will be 
identified by the field names in the file on the 
left-hand side of the assignment statement, such as 
file a. 


The files that result from set operations will 
not contain any duplicate records. 
Since this 
feature is provided by bUilding an index, the com- 
bined length of the records involved in a set opera- 
tion cannot exceed the maximum length of a key, 118 
characters. 


The UNION clause of the ASSIGN command allows 
the user to concatenate two files (without duplicate 
records). 
Here, the agents file of the realty data- 
base is read into two temporary files, which are 
then rejoined with the UNION clause of the ASSIGN 
command. 


> read into a agent name agent salary 
» 
where agent_salary >= 20000; 


A sequential search will be 
used to satisfy the WHERE clause. 


> read into b agent name agent salary 
» 
where agent_salary <= 20000; 


A sequential search will be 
used to satisfy the WHERE clause. 


> assign c = a union b 
> print c ; 


agent_name 


O'Brian, Sean 
Adams, Shirley 
Jones, Frank 
Jackson, Robert 


> 


20000.00 
25000.00 
15000.00 
12100.00 


The INTERSECT clause of the ASSIGN command al- 
lows the user to create a temporary file out of 
those records that are common between two other 
files. 
The following ASSIGN command creates the 
temporary file d from the records that are common to 
both file a and file b. 
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> assign d = a intersect b 


> print d ; 


agent_name 


O'Brian, Sean 


> 


20000.00 


The MINUS clause of the ASSIGN command allows 
the user to create the difference between two files. 
The following example creates a file e which has the 
records from file a which are not also in file b. 


> assign e = a minus b 
; 


> print e ; 


agent_name 


Adams, Shirley 


> 


25000.00 


III.J. 
The EXECUTE Command 


The syntax of the EXECUTE command is: 


> EXECUTE file-name 


EXECUTE is used to run sequences of queries in 
a file you create with an editor. 
The EXECUTE com- 
mand can be used to direct INFORMER to take its com- 
mand input from the file. 
Commands will be taken 


from the file until the end of file is encountered. 
Then INFORMER again prompts the user for input at 
the terminal. 
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The 
que~y file billspaid contains the following 
commands: 


read into x cname balance 
whe~e balance 
a 
print x 


A query file can be executed 
f~om the operating 
system level by including it on the command line, as 
follows: 


A> informer stores billspaid 


When a query file is executed, the series of 
commands is automatically invoked. 


> execute "billspaid" 
; 


read into x cname balance where balance 
a 


> print x 


cname 


Field, 
W. 


Court, S. 
English, D. 


balance 


0.00 
0.00 
0.00 


EXECUTE may be abbreviated EX as shown below. 


> ex "billspaid" 
; 


III. K. 
The RUN Command 


The RUN command runs a UNIX operating system 
command: 


RUN "command" ; 


When the operating system command finishes run- 
ning, the INFORMER prompt reappears. 


You can also run a UNIX operating system com- 
mand by preceding the command with an exclamation 
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point (!). 
An operating system command to list your 
directory would be "!ls" or, to edit a file, "!vi". 
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IV. 
Syntax Synopsis 


Three of the commands of INFORMER -- 
PRINT, 
UNLOAD, and READ -- use similar syntax. 
The PRINT 
statement displays query results directly; the READ 
statement prepares a temporary database file which 
remains available for the duration of the INFORMER 
session; and the UNLOAD command prepares a permanent 
operating system file which is in the format of IN- 
FORMIX load files. 
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Syntax 
Desc~iption fo~ READ, PRINT, and UNLOAD 


READ {INTO X} 
{UNIQUE} fieldlist {WHEREclause 
} 
{JOININGclause} 


PRINT fieldlist 
{WITHOUT HEADINGS 
} 
{TO "filename" 
} 
{TO PIPE 
"p~og~amname"} 


{WHEREclause 
} 
{JOININGclause 
} 


UNLOAD fieldlist 
{TO "filename" 
} 
{TO PIPE 
"p~og~amname"} 


{WHEREclause 
} 
{JOININGclause 
} 


Ze~o 
o~ 
mo~e of the choices in the 
cu~ly 
b~ackets 


can be used in any 
o~de~. 


fieldl.ist 
= 


JOININGclause 


WHEREclause = 


one 
o~ 
mo~e field names 
o~ file 
names 
sepa~ated by commas, 
blanks, 
o~ the 
wo~d "and" 


the 
keywo~ds FROM JOIN ON 


o~ the 
keywo~d JOINING followed 
by field = field 
o~ 


field = OPTIONAL field 


the 
keywo~d WHERE followed by a 
logical 
exp~ession 


logical 
exp~ession 
field relop constant 
or 
logical-expression 
logop 


logical-exp~ession 


where a 
~elop is one of the relational 
ope~ato~s 


<> 
< 
> 
<= 
>= 
MATCHES 


and a logop os one of the logical 
ope~ato~s 
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V. 
ADVANCED FEATURES 


V.A. 
Sample Database 


The following schema is for a database used by 
a bank. 
This database is used for examples in the 


remainder of this section. 
Here is the structure of 
the bank database as reported by the PRINT SCHEMA 
command: 


database bank 
file loan 


field loan num 
type serial start 1000 index primary 


field borr-num 
type long 
index dups 
field loan-date 
type date 
field loan:type 
type char 
length 15 
field loan amt 
type money 
field primaryoff type long 
field secondoff 
type long 
field term_type 
type char 
length 2 
field rate 
type float 


file customer 


field cust num 
type serial 
index 
field cust-Iname 
type char 
length 15 
field cust-fname 
type char 
length 10 
field cust-addr 
type char 
length 20 
field cust:city 
type char 
length 15 
field state 
type char 
length 2 
field zip 
type char 
length 5 
field cust_phone 
type char 
length 18 
field employer 
type char 
length 25 
field salary 
type money 
field hired 
type date 
field co_app 
type long 
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file employee 


field emp num 
type serial 
index 
field emp-Iname 
type char 
length 15 
field emp=fname 
type char 
length 10 
field emp_addr 
type char 
length 20 
field emp_city 
type char 
length 15 
field emp phone 
type char 
length 13 
field emp=hired 
type date 
field emp_dept 
type integer 
index dUps 
field emp title 
type char 
length 20 
field emp=salary 
type money 


file depar,tment 


field dept num 
field dept-name 
field dept=mngr 


end 


type integer 
index 
type char 
length 20 
type long 


V.B. 
Sorting 


INFORMER sorts query responses with the SORT 
clause in a PRINT command following a READ. 
Output 
may be sorted on one or more of the fields named in 
the query. 
A total of eight fields and 120 charac- 
ters may be used in a sort. 
The SORT clause should 
appear in the PRINT statement following a READ 
statement. 


Unless you request sorted output, the records 
in query results will not appear in sorted order. 


Each of the fields"for the SORT command may be 
specified to be sorted in either ASCENDING or 
DESCENDING order. 
The default is ASCENDING. 
All 
fields specified by SORT must be indexed, Which may 
be accomplished With READ and a temporary file. 


I~ the example below, a temporary file, cst, is 
created in 
orde~ to sort fields joined from dif- 
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ferent files. 
The sort will be alphabetical (AS- 
CENDING is default) by the customers' last name, and 
by loan number within customer name. 
If there is 
more than one loan for a borrower, the higher loan 
number (the more recent loan) will be listed first, 
since DESCENDING order of loan number is requested. 


read into cst 
cust num, cust fname, cust lname, 
-loan num,-loan date 
- 
joinIng cust_num = borr_num; 


print cst 
sort by cust_lname, loan num descending; 


V.C. 
Creating Aliases 


The.most common joins used in INFORMIX are 
joins between files. 
Joins within files are rarely 
necessary. 
However, cases do arise where it is use- 


ful to join a file to itself to retrieve specific 
information. 
This is called a self-join. 


An example of a self-join can be drawn from the 
bank database. 
The customer file contains a field 
for co-applicant. 
This field contains a customer 
number which references the co-applicant's own cus- 
tomer record. 
In order to access information on 
both the applicant and the co-applicant, it is 
necessary to join the customer file to itself. 


Since JOINING expects fields to come from dif- 
ferent files, you must create an alias for the 
customer file. 
(Otherwise the JOINING would be try- 
ing to work with fields having the same name within 
one file, which is not legal.) 


alias 
print 
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This request will yield identifying numbers, 
employers, and salaries on both applicant and co- 
applicant for all records including a co-applicant. 


The field names shown in the result are the 
same for applicant and co-applicant. 
You can rename 
the fields for the output with temporary field 
names. 
These new field names are listed in the 
PRINT or READ command line, in equation form. 
For 
example, you can rename cus.salary and cus.employer 
to distinguish between applicant and co-applicant 
data in the output: 


alias cus = customer; 
print cust num, employer, salary, co app, 
coapp-emp = cus.employer, 
- 
coapp-sal = cus.salary 
joining co_app = cus.cust_num; 


This query prints cust num, employer, and salary for 
customers and their 
co~applicants. 
The co- 
applicant, employer, and salary field are renamed 
coapp emp and coapp sal for the sake of a more read- 
able report. 
- 


You can assign new names temporarily to fields 
at any time, whether in the course of doing a join 
or self-join, or in order to change the headers 
(column names) on query results. 


V.D. 
Optional Joins 


Optional joins allow you to select records from 
a file, even when there are no corresponding records 
in a joined file. 
The word optional means that a 
match for the JOINING is optional. 
First, here's 
another example of a standard JOINING: 
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> print cname item 
» 
where balance 
= 0 
» 
joining cname = oname; 


..... 
fa 


cname 


Court, S. 
Court, S. 
English, D. 
English, D. 


item 


Saw 
File 
File 
Hammer 


The name "Field, W." does not appear in this 
join because, even though Field has a zero balance, 
he does not have anything on order, and therefore 
has no entry in the oosme field of the order file. 
If you want to see fields from the file on the 
left-hand side of the join expression, even if there 
is no match found from the file on the right-hand 
side, use the OPTIONAL syntax. 
Blanks will be shown 
for records for which no match is found. 


> print cname item 
» 
joining cname = optional oname 
» 
where balance = 0 


cname 


Field, 
W. 
Court, S. 
Court, S. 
English, D. 
English, D. 
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V.E. 
Multiple Joins 


INFORMER can create multiple joins among 
several temporary or permanent files. 
The bank da- 
tabase can show the use of multiple joins if you add 
a departments file, containing a record for each 
bank department (bookkeeping, trust, customer ser- 
vice, etc.). 
The schema is as follows: 


database bank 
file department 


field dept no 
field dept-name 
field dept:mngr 


end 


type integer 
index 
type character 
length 20 
type long 


First create an alias for the employee file, 
in 
order to access the employee number field for both 
the employee and the department manager. 
You can 
then join the files on the employee and department 
manager name fields. 
The query would be as follows: 


> alias empe = employee; 


> read into info 
» 
dept_num 
» 
manager = empe.emp_lname 
» 
emp fname 
» 
emp-lname 
» 
title = emp title 
» 
joining emp-dept = dept num 
» 
and dept_mngr 
empe.emp_num 
> print info 
; 


This query renames two of the output fields 
(manager and title) to make the output more read- 
able. 
The example prOVides for two joins, but it is 
possible to join fields from up to six files at 
once. 
This limit depends on operating system limi- 
tations on the number of files that can be open at 
one time. 
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V.F. 
Arithmetic Expressions 


Arithmetic expressions can be used in INFORMER 
statements in WHERE clauses, with temporary field 
labels, or in variable assignments. 
In WHERE 
clauses, a selection can be based on an arithmetic 
expression involving more than one field, 
such as 


print file where field1 * field2 > 100 ; 


An example from the bank database would be to print 
all customer files where the salaries of applicant 
and co-applicant total over $40,000. 
The query in- 
cludes an alias for the customer file to allow a 
join within the file. 


> alias cus = customer 
> print customer where salary 
+ cus.salary > 40000 
» 
joining co_app 
= cus.cust_num ; 


A field tot salary may be created to hold the 
value of the total salary for both applicant and 
co-applicant. 
The arithmetic expression is in an 
equation that is part of the PRINT statement. 


> alias cus = customer ; 
> print 
cu~t num, salary, co_app, cus.salary, 
» 
tot saIary = salary 
+ cus.salary 
» 
joining co_app = cus.cust_num ; 


Mathematical expressions use the arithmetic 
operators, alone or in combination with the rela- 
tional and logical operators. 
The arithmetic opera- 
tors are: 


Arithmetic Operators 


+ 
add 
subtract 
/ 
divide 
* 
multiply 


These arithmetic operators can be used to: 


~ 
Indicate the sign of a number 
(+ or -) 


~ 
Add, subtract, multiply, or divide with any 
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combination of field values and constants 


Arithmetic expressions can function in seles- 


tions with PRINT and READ statements. 


You can use arithmetic expressions in PRINT and 
READ statements, to make comparisons between fields 
or to perform calculations on fields. 


Using arithmetic expressions with PRINT and 
READ does not alter the values of fields. 
Instead, 
you make selections based on -the results of calcula- 
tions. 


Arithmetic expressions can make use of a "vari- 


able" to hold the results of calculations or to pro- 
vide an alternate name for a field. 


A named variable is assigned a value with the 


LET command. 
The variable can be printed, or used 
in the WHERE clause. 
In the following example, a 
variable is assigned for the average of (customer 
salary 
+ 5000). 
AVERAGE and other aggregate vari- 


ables will be discussed more fully in the next sec- 
tion. 


let hisal = average of salary 
+ 5000 
print hisal, cust num, salary 


where salary > hisal 


V.G. 
Aggregate Variables 


INFORMER counts records, totals values of 
fields, 
and computes statistics with aggregate vari- 
ables such as COUNT, 
AVERAGE, 
TOTAL, MIN, and MAX. 
The aggregate desired can be assigned using the LET 
command, printed using PRINT, or read into a tem- 
porary file using READ INTO. 


READ and PRINT statements may not contain both 
aggregates and other fields in the same statement. 
However, a variable with aggregate information may 
be created with a READ statement, and printed with 
other fields in a PRINT statement. 


INFORMIX. 
43 


INFORMER Query Language 


The following statements are examples from the 
bank database. 


print count of loan num; 
let av = average of-loan amt; 
read into rmin min of rate; 


Here is the syntax for commands using aggre- 
gates: 


LET user variable 


{ COUNT } 
{ TOTAL } 
{AVERAGE} OF expression 
{ 
MIN 
} 
{ 
MAX 
} 


{ COUNT } 
{ TOTAL } 
PRINT {AVERAGE} 
OF expression 
{ 
MIN 
} 
{ 
MAX 
} 


READ into temp_filename 


{ COUNT } 
{ TOTAL } 
{AVERAGE} OF expression 
{ 
MIN 
} 
{ 
MAX 
} 


The expression may be only a field name, or ar- 
ithmetic expressions may be applied in statements 
involving variables. 
Aggregates can also be used 
with a WHERE clause in order to affect only specific 
records. 
The following statement instructs INFORMER 
to print a count of the records where there is some 
entry (not 0) in the co app field. 
In the bank da- 
tabase, this produces a-count of customer records 
that have a co-applicant. 


print count where not co_app = 0 ; 


When using arithmetic expressions in a state- 
ment following an aggregate, the aggregate of the 
total expression following it is computed. 
The 
statement "print total of loan amt - 1000" is read 
as "print total of (loan_amt --1000)." 
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V.H. 
The Date Functions 


INFORMER has functions that allow you to create 
and/or manipulate all three types of date fields. 


The syntax for using the date functions is dif- 
ferent depending on whether you are using.;he PRINT 
or the READ command. 
With PRINT, 
you must give a 
label or title to the function: 


print label = function(datefield) 


The query results use the label as a column heading. 


With READ, a label is not required. 


V.H.1. 
The DAY, 
MONTH, and YEAR Functions 


The DAY, 
MONTH, and YEAR functions are used to 
extract the day, month, and year from a date field 
or other expression. 
You can use the DAY, 
MONTH, 
and 
YEAR functions anywhere you would normally use 
an expression. 


The syntax is as follows: 


For PRINT: 


x 
day(expression) 
x 
month(expression) 
x 
year(expression) 


For READ: 


day (e xpre ss ion) 
month(expression) 
year(expression) 


where x is any label, and where expression is the· 
name of a DATE field or any other expression. 
The 
DAY, 
MONTH, and 
YEAR functions correctly select the 
day, month, and year from any database field of type 
DATE, 
YDATE, or EDATE. 
If you use an expression 
which is not one of these types of database fields, 


II~FORMER assumes that the format is that of the date 
type. 
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You might use these functions to limit the 
scope of a query with the READ command: 


read into x listings 
where month(date listed) > 2 
and year(date_1Isted) > 82; 


This READ command selects records in which the 
date listed field contains a month between March and 
December and a year later than 82. 


The DAY, MONTH, and YEAR functions also enable 
you to sort a report by days, months, and years. 
For example: 


read into x 
days 
= day(date listed), 
months = month(date listed), 
years 
= year(date listed), 
date_listed; 
- 


print x 
sort by years, months, days; 


V.H.2. 
The HOY Function 


The MDY function lets you convert three expres- 
sions into a date. 
You can use it anywhere you can 
use an expression. 
For example: 


read into x listings, 
new_date 
= mdy(12,1,84) 


names a temporary field new date and gives it the 
value 12/1/84 as a result of the operation of the 
MDY function. 


MDY will attempt to format any three numbers 
given to it as a date in standard MMDDYY format. 
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V.H.3. 
The WEEKDAY Function 


The WEEKDAY function lets you determine the day 
of the week for a particular date. 


weekday(expression) 


where expression is usually a date field. 
The WEEK- 
DAY function returns an integer from 0 through 6, 
with 0 corresponding to Sunday, 1 to Monday, 2 to 
Tuesday, etc. 


--In practice, you might use the WEEKDAY function 
as follows: 


read into x oname 
where (weekday(o date) 
= 5) 
print x ; 
- 


V.H.4. 
The DATE, EDATE, and YDATE Functions 


The DATE, 
EDATE, and YDATE functions allow you 
to convert the value of an expression to type DATE, 
EDATE, or YDATE, then store the value in a temporary 
variable. 


The syntax is: 


temp field 
DATE(expression) 
temp-field = YDATE(expression) 
temp=field = EDATE(expression) 


You might use these functions to convert data stored 
in one type of date field into another format for 
printing. 
For example, if date-posted is a YDATE 
field, you can convert it to EDATE format and print 
it with the following command line: 


print new date = edate(date_posted) 
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V.I. 
Updates. Additions. and Deletions 


INFORMER has three commands -- UPDATE, DELETE, 
and ADD -- to change, remove, or add data. 


The ADD command creates a new record and adds 
specified data for the fields named, or adds data to 
a blank field. 


The syntax for the ADD command is: 


ADD filename 
field a 
x 
field b = Y ; 


To add a new record, name the database file, 
and then name each field and assign a value to it in 
equation form. 


add orders item = Hammer 
; 


With a WHERE clause, you can add data to a 
blank field for an eXisting record: 


add orders item = Saw 
where oname 
= "Robin, R." 
j 


The UPDATE and DELETE commands permit modifica- 
tion or deletion of database records in mass. 
If 
all retail prices in a store's database are to be 
increased by ten percent, all records can be updated 
at one time. 
If all orders from a specific supplier 
are to be deleted, they can be removed with a single 
DELETE command. 
Example commands are: 


update supplies price = price * 1.10; 


delete orders 
where supp matches "XYZ Wholesalers"; 


Filenames must be specified before the field 
names. 
Following the UPDATE or DELETE command, IN- 
FORMER displays the affected fields, one at a time, 
and prompts to verify that the change is desired. 
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V.I.1. 
The NOPROMPT Option 


UPDATEs and DELETEs are called batch or mass 
operations because they potentially a11eCt many-- 
records. 
Since the effects of DELETE and UPDATE can 
be permanent, these powerful commands should be used 
with caution. 


DELETE and UPDATE interrogate you before remov- 
ing or modifying a record. 
To suppress this in- 
teraction, use the NOPROMPT option. 
The NOPROMPT 
option causes DELETE and 
UPDA~to remove or change 
records without asking you first. 


The syntax for the NOPROMPT option is: 


{DELETE} NOPROMPT filename [WHERE-clause] [JOINING-clause]; 
{UPDATE} 


For example: 


delete noprompt orders 
where supp matches "XYZ Wholesalers" ; 


If you create an INFORMER query file including 
UPDATE or DELETE commands, you must use the NOPROMPT 
option. 


V.I.2. 
Deleting Every Record 


When you omit a WHERE clause, the DELETE com- 
mand operates on the entire database file. 
The com- 
mand 


delete orders ; 


makes every record in the orders file a candidate 
for deletion. 
Using this command with NOPROMPT 
silently deletes every record in the file. 


V.I.3. 
Updating Every Record 


If you omit a WHERE clause, the UPDATE command 
affects every record in the database file. 
For ex- 
ample, 


update orders oname 
= "Cranshaw" 


changes the last name in every record in the orders 
file to "Cranshaw". 
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V.I.4. 
Deleting Through JOINING 


The DELETE command can use a J01n to delete 


~eco~ds based on a 
compa~ison with the value of a 
field in 
anothe~ file. 
Fo~ example, suppose you 
want to delete all 
custome~s 
f~om the customers file 
who have 
o~de~ed a 
hamme~. 


delete 
custome~s 


joining cname = oname 


whe~e item = 
"Hamme~": 


V.I.5. 
Updating Through JOINING 


Use updates with joins to modify a field based 
on a 
compa~ison with a field in 
anothe~ file. 
Fo~ 


example, you could increase the quantity of items 


orde~ed by 50, using UPDATE with a JOINING clause: 


update orders quantity 
quantity 
+ 50 
joining cname 
= oname ; 


V.J. 
Prompting for Variables 


You can prompt for the value of variables when 
executing commands. 
INFORMER'S PROMPT command 
prompts you to enter the value of some field within 
the database, often for the purpose of updating in- 
formation with a subsequent UPDATE command. 


If the bank has hired a new loan officer who 
will replace the previous secondary officer on a 
number of existing loans, we can write an INFORMER 
query file for the update. 
The query file prompts 


for the loan number for each record to be changed. 
Here is the query file, named qry5: 


print loan num 
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prompt for numb using "Enter Loan Number: 
" 


update secondoff = 10 
where loan num = numb 


The query file prints the list of 
cur~ent loan 
numbers first, 
to show the operator the choice of 
responses to the prompt. 


In response to the prompt, enter a loan number 
for the first record to be updated. 
The UPDATE com- 
mand will then change the secondoff field for that 
record to "10". 
A DELETE in response to the "Enter 
Loan Number:" prompt interrupts query file execution 
and returns you to the INFORMER prompt. 


In another example, 
PROMPT FOR is used to up- 
date employee salaries. 
The executable file 
qryraise prompts for both the employee number and 
the percentage salary increase: 


prompt for empn using "Employee Number: 
"; 


print emp_fname, emp_lname where emp_num = empn; 


prompt for raise using "Raise amount: 
"; 


update employee emp salary = emp_salary * raise 
where emp_num 
~ empn 


The results of this query are displayed below. 
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INFORMER Relational Query Language 
INFORMIX version 3.2 
Copyright (C) 1981, 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-000001 


Type .help for sample commands. 


Database "bank" has been selected successfully. 
> ex qryraise 
; 


> prompt for empn using "Employee Number: 
" 


Employee Number: 18 
>> print emp_fname, emp_lname where emp_num = empn 


emp_fname 
emp_lname 


Margaret 
Givens 


>> prompt for raise using "Raise amount: " 


Raise amount: 1.10 
>> update employee emp_salary = emp_salary * raise 
» 
where emp_num= empn ; 


emp_num· 
emp lname 
emp-fname 
emp:addr ' 
emp city 
empJ>hone 
emp hired 
emp-dept 
emp-title 
emp:salary 


18 
Givens 
Margaret 
3301 Winchester 
Palo Alto 
856-2390 
01/21/82 
7 
. 
Programmer 
$28700.00 


Modify? (y or n): y 
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Record updated: 


emp num 
emp-lname 
emp-fname 
emp-addr 
emp-city 
emp-phone 
emp-hired 
emp-dept 
emp-title 
emp:salary 


18 
Givens 
Margaret 
3301 Winchester 
Palo Alto 
856-2390 
01/21/82 
7 
Programmer 1 
$31570.00 


> bye 
Program over. 


In this case, the user executes the qryraise 
file for each employee raise. 
Alternatively, the 


records for all employees receiving equal percentage 
increases in salary could be updated with one UPDATE 
command using the appropriate WHERE clause. 


There is no error checking on values given to 
the program in response to the prompt. 


V.K. 
Locking Database Files 


When working on INFORMER queries or mass up- 
dates in a multi-user environment, it may be useful 
to prohibit access by other users to some database 
files. 
This will assure that data is not altered by 
another user while your operation is being run. 
Temporary locking of files is available through LOCK 
and UNLOCK commands. 
A LOCK or UNLOCK command is 
followed by the list of permanent database files to 
be locked or unlocked. 


LOCK or UNLOCK 
filename, filename; 


The locked files will remain inaccessible to 
other users until they are unlocked with the UNLOCK 
command. 
However, if you leave INFORMER without un- 
locking locked files, 
INFORMER will unlock them. 


The EXCLUSIVE option to the LOCK command allows 
a user to lock a file exclusively so that no other 
user can access it. 
The syntax for this option is: 
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lock exclusive file_name 


V.L. 
Adding and Deleting Indexes 


You can add or delete indexes on fields using 
the same commands that you use .in DBSTATUS : 


> ADD INDEX FOR field-name 


> ADD INDEX FOR field-name ALLOWING DUPS 


or 


> DELETE INDEX FOR field-name 
; 


You can use the ADD INDEX command on a field of 
any type. 
The field can contain only unique values 
unless the ALLOWING DUPS clause is added to the com- 
mand. 
If the field to be indexed Is of type CHARAC- 
TER, it may not be longer than 118 characters. 
An 
index on any field (except a PRIMARY key) can be 
deleted using the DELETE INDEX command. 


V.M. 
Changing the Location of Temporary Files 
Using DBTEMP 


The DBTEMP variable specifies the location of 
temporary files created by a READ command in INFORM- 
ER and ACE. 
In UNIX systems, the /tmp directory is 
used by default if no DBTEMP variable is set. 
On 
MS-DOS systems, temporary files are placed in the 
current directory if no DBTEMP variable is set. 


Naming a specific DBTEMP path for temporary 
files allows you to use some other directory, even a 
directory on another device, for temporary files. 


The DBTEMP variable can be set in the UNIX en- 
vironment either during a session, or permanently 
(in the.login or .profile file). 
For the C shell, 
use the "setenv" command. 
Only one location may be 
specified for "temporary files. 
An example is shown 
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below. 


% setenv DBTEMP /z/dbfiles 


where Iz/dbfiles is the path name for the temporary 
files directory. 


The comparable Bourne shell commands would be 


$ DBTEMP=/z/dbfiles 
$ export DBTEMP 


For MS-DOS systems, use the following syntax: 


A> set DBTEMP=c:\tempdir 


The above command puts temporary files into the 
directory tempdir on drive C. 


V.N. 
HELP 


To see the syntax of any INFORMER command, 
enter HELP or H followed by RETURN, and examples of 
the commands available within the INFORMER language 
will be displayed. 


Here is how HELP works: 


> h 
Help command. 


Typical INFORMER commands (some using the manual's 
bank database) are offered below. 
> print employee where emp lname = "Pearson" 
> print loan without headings ; 
> print loan num, borrnum, loan date 
» 
where loan_date < "03/04/82" -; 


> print 
»»> print 
»» 


mm of loan date 
= month(loan-date), 
dd-of-Ioan-date = day(loan date), 
yy-of-Ioan-date = year(loan date); 
date of loan date = date(loan date), 
edate of loan date = edate(loan date), 
ydate:of:loan:date 
= ydate(loan:date); 


> print customers where 
» 
balance 
0 to "zerobalance" 
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> read into x emp lname emp fname dept_name 
» 
joining dept name = emp dept ; 
> ~rint x; 
- 
- 


> read into x cname item and quantity 
» 
joining cname = oname ; 
> read into y cname, unique item, quantity 
» 
joining cname = oname where balance = 0 
> print y; 


> read into uprim unique primaryoff 
> print uprim ; 
> alias emp2 = employee 
> print loan num 
» 
primary =-emp lname 
» 
secondary = emp2.emp lname 
» 
joining 
- 
» 
primaryoff = emp num secondof! 
» 
optional emp2.emp_num ; 


> read into temp1 customer 
» 
where cust city = "San Jose" 
> read into temp2 customer 
» 
where salary > 20000. 
; 
> assign temp3 = temp1 union temp2 ; 
> assign temp3 = temp1 intersect temp2 
> assign temp3 = temp1 minus temp2 ; 
> print count of loan num ; 
> print count where loan amt > 10000. 
; 
> print min of emp_salary, max of emp_salary 


> let av = average of loan amt 
> print av ; 
- 
> print loan num cust lname cust fname 
» 
joining borr num =-cust num 
- 
» 
where loan_amt > av ; 
- 


> prompt for Iname using 
» 
"Enter customer's last name: " ; 
> prompt for fname using 
» 
"Enter customer's first name: " ; 
> print customer where cust Iname = lname and 
» 
oust_fname 
= fname; 
- 


-> read into sortaddr customer; 
> print sortaddr sort by cust_addr 


> lock employee ; 
> lock exclusive employee ; 
> update employee emp_salary 
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» 
where emp salary < 20000 
> unlock employee 
> delete employee where emp_num = 11 


> add department dept num = 10 
» 
dept name = "Employee Well-being" 
» 
dept-mngr = 5 ; 
> update employee emp_dept = 10 where emp_num 
5 


> unload loan to "unloadfilename" 


> delimiter "ascii character" ; 
> delimiter integer, 
> unload ascii loan to "unloadfilename" 
> print schema 
> print schema 
> print status 
> print status 


, 
for employee 
; 
for employee 


> run "operating system command" 
> execute "execfilename" 
> run "operating system command" 
> execute "execfilename" 
; 


> bye 
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VI. 
Appendix - Error Messages 


error 7001: 


An illegal integer value has been entered. 


error 7003: 


Identifier too long. The maximum length allowed is 
50. 


error 7004: 


Quoted string too long. The maximum length allowed 
is 50. 


error 7005: 


A quote has been found for which there is no match- 
ing quote. 


error 7006: 


An illegal character has been found. 


error 7009: 


When not reading into a temporary file, a sort can- 
not be done unless an index has already been created 
for the field using DBSTATUS. 


errQr 7010: 


The field specified could not be found. 


error 7015: 


The database specified could not be found. 


error 7016: 


The file specified could not be found. 
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error 7023: 


An index could not be created for the sort clause. 


error 7024: 


There is no data in the file. 


error 7025: 


The field specified is not in the current file. 
All 
fields used in the SORT clause must be in the 
current file. 


error 7026: 


Sorting on calculated fields must be done by reading 
into temporary file. 


error 7029: 


The temporary file specified could not be open or 
crea ted. 


error 7030: 


The temporary file specified could not be recon- 
structed. 


error 7032: 


The corresponding fields in the JOIN clause must be 
the same type and length. 


error 7039: 


The execute file specified could not be opened. The 
file probably does not exist. 
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error 7040: 


The two temporary files involved in set operations 
must be union compatible. They must contain the same 
number of fields. 
Each field must be of the same 
type and length as its counterpart in the other 
. 
file. 


error 7041: 


An illegal floating-point number has15een entered. 


error 7042: 


Each temporary file name used in an ASSIGN statement 
must be unique. 


error 7043: 


The record length for a file used in an ASSIGN 
statement cannot exceed 118 bytes. 


error 7045: 


The UNIQUE specifier can only be used in a READ 
statement which creates a temporary file. 


error 7046: 


Too many UNIQUE fields were specified in this READ 
command. 
The maximum number of fields is 200. 


error 7047: 


The output file specified could not be created. 


error 7048: 


The limit on the number of fields in a temporary 
file is 200. 
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error 7055: 


The limit on the number of temporary files is 26. 


error 7069: 


Wildcard matching cannot be used for non-character 
fields. 


error 7080: 


The field specified does not exist in the temporary 
file specified. 


error 7081: 


A memory allocation error has occurred. 


error 7082: 


The query has exceeded the maximum of 8 files. 


error 7083: 


The query has exceeded the maximum of 8 joins. 


error 7084: 


The query has no joins but references more than one 
file. 


error 7085: 


There are too many joins in the query. There is 
probably a circular join in the query. 


error 7086: 


There are not enough joins among the referenced 
files in the query. 
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error 7087: 


The file specified does not appear in the join list. 


error 7088: 


A join path does not exist between all the refer- 
enced files. 


error 7091: 


The identifier specified is not a temporary file. 


error 7092: 


A temporary ISAM file could not be built to contain 
modification data. 


error 7093: 


The query has exceeded the expression storage space. 


error 7094: 


The query has exceeded the constant storage space. 


error 7096: 


The field specified is not a field in the file to be 
modified or added to. 


error 7097: 


The new record has one or more duplicate field 
values where duplicate values are not allowed. 


error 7098: 


A unique id could not be created for a new record. 


error 7100: 


An UPDATE command may not modify a join field. 
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error 7101: 


The file to be added to may not be part of a JOIN or 
WHERE clause. 


error 7102: 


Character fields cannot be compared with non- 
character constants. 


error 7103: 


Character fields cannot be assigned non-character 
values. 


error 7104: 


There is a failure to write a tuple to a file in the 
unloading process. 


error 7105: 


The database file specified could not be opened •. 


error 7106: 


The deletion of this record failed. 


error 7107: 


This record cannot be updated. 


error 7108: 


The temporary file created for updates cannot be 
written to. 


error 7109: 


The record is locked. 
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error 7110: 


An index could not be added for the set operation 
resul t file. 


error 7111: 


An isstart could not be done for set operation 
resul t file. 


error 7112: 


The name specified cannot be used as a temporary 
file name. It is already the name of a permanent 
file or field or variable. 


error 7113: 


An alias name can be assigned only to a permanent 
file or an actual temporary file (not another 
alias). 
An alias name cannot be used to re-name a 
temporary file of the same name. 


error 7114: 


Use the permanent file name for UPDATE, 
ADD, and 
DELETE. 


error 7115: 


Informer has exceeded the maximum number of 20 vari- 
ables. 


error 7116: 


The identifier specified cannot be used as a vari- 
able name. It is already the name of a file or 
field. 


error 711'(: 


Totals and averages cannot be computed for character 
fields. 
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error 7118: 


The query has exceeded the maximum of 8 sort fields. 


error 7119: 


In an optimized sort, all the sort fields must come 
from one existing relation. 


error 7120: 


An index could not be created for a temporary file. 


error 7121: 


An update cannot be done on a file which is on the 
right side of an optional join. 


error 7122: 


Operations cannot be done on composite field speci- 
fied. 


error 7123: 


Permission is not granted to use field specified. 


error 7124: 


Permission is not granted to .nter data into speci- 
fied field. 


error 7125: 


Permission is not granted to add records to speci- 
fied file. 


error 7126: 


Permission is not granted to delete records from 
specified file. 
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error 7127: 


Permission is not granted to read any of the output 
fields. 


error 7129: 


One lock or unlock command may not specify more than 
8 files. 


error 7130: 


The file specified cannot be locked. 


error 7131: 


The file specified is not a permanent file in the 
database. 


error 7132: 


Updates and additions cannot be performed on serial 
type fields. 


error 7133: 


Permission not granted to use member field specified 
of composite field specified. 


error 7134: 


An index already exists for the field specified. 


error 7135: 


The field specified is a bad key. 


error 7136: 


An attempt was made to add a unique index when the 
field has duplicate values. 
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error 7137: 


The file specified cannot be opened with exclusive 
locking. 


error 7138: 


An ASCII-to-date conversion error has occurred. 


error 7139: 


An ASClI-to-binary conversion error has occurred. 


error 7140: 


An attempt was made to divide by zero. Result was 
set to zero. 


error 7141: 


This operation on the file is not allowed because 
you do not have CONTROL access to the file. 


error 7142: 


Date conversion error. 
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I. 
Introduction 


A menu is a list of choices that is displayed 
on a terminal. 
It allows you to select one of the 
choices and takes action based on your selection. 
The 
DBMENU program is based on Relational Database 
System's INFORMIX database management system. 
The 
RDS Menu Builder, 
DBMENU, makes it easy for you to 
set up a professional menu system quickly--a menu 
system that can enhance your software by making it 
easier to use. 


The DBMENU database has two schema (data 
definition) files, 
one form file (for data entry), 
and a program file. 
You can change DBMENU's default 
names for these files, if desired. 
If you are going 
to have more than one menu-building system, you must 
give the menu system databases different names, or 
else store them in separate directories. 


This guide assumes that you are familiar with 
the operation of the 
PERFORM program and (if you're 
going to modify files) with the DBBUILD and FORM- 
BUILD programs. 
Beginning with the simplest setup 
using the default database 
(menu) and the 
DBMENU 
program, this guide continues by explaining how to 
use other names for the program and database files. 
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11_ 
Setting Up a Menu System 


The 1NFORMIX PERFORM and DBMENU programs must 
be available on your system. 
(On UNIX, 
DBMENU must 
be in a commands directory such as /bin.) You must 
have copies of the menu_dbd, menus.idx, menus_dat, 
menuitem_dat, menuitem_idx, and menuform.frm files 
in the directory in which you are working. 


The menu database, as shipped, is ready for you 
to load with the menus you want to use. 
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III. 
Designing Your Menu System 


Before you start loading your menu database, 
design the structure of your menu system on paper. 
A menu system is structured as a hierarchy, with the 
menu named main at the top, or root, of the struc- 
ture. 
DBMENU displays the main menu when you first 
call the menu package. 
The name main may not be 
changed--each menu system must begin with a menu 
named main at the top of the hierarchy. 


Each menu selection can either call another 
menu or execute an operating system command. 


Below is the design of a sample menu system. 


main menu 
menu a 
menu n 
-program 21 
program:22 
menu 
0 
-program 23 
program-24 
program 1 
- 
menu b 
- 
-program 2 
program-3 
program-4 
program:5 
menu c 


menuJ' 


program 41 
program:42 
menu z 
-program 60 
program-61 
program_8 
- 


This menu system shows the main menu with three 
submenus (menu a, menu b, and menu c). 
You can call 
other programs-and menus from each-of the submenus. 
DBMENU allows you to nest menus.to 19 levels, 
although only four levels of menus are shown in the 
example. 
Each of the 
progr~m names (program 1, 
program 60, etc.) represents an application program 
(or UNIX Shell script). 
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IV. 
BUilding Your Menu System 


Call the 
PERFORM program by glvlng the follow- 
ing command in response to the system prompt. 


perform menuform 


PERFORM will display the following form on your 
screen. 


============================= MENU ENTRY FORM ======================== 


Enter menu name, title, and spacing for all menus first. 
Then complete Selection Section for each selection of each menu. 


Menu name: 
[ 
Menu title: 
[ 
Line spacing: 
[0] 
] 


Selection number: 
0 


Selection 
text: 


Program to 
execute: 


Next menu name: 


SELECTION SECTION Selection type: 


=====~================================================ 
================ 


The top section of the form contains whatever 
information about the particular menu you wish to 
store. 
The Selection Section (the lower portion of 
the form) 
has information about each item that you 
can select from the menu. 
The easiest way to build 
a menu system is to fill in the name, title, and 
spacing information about all the menus before 
entering any information in-the selection section. 


Select the Add option from the PERFORM menu by 
pressing a. 
The cursor will move to the Menu name 
field. 
Enter the name of the menu. 
Press RETURN to 
move the cursor to the Line spacing field. 
After 
filling in this field, press RETURN to move the cur- 
sor to the next field. 
After you have entered a 
Menu title, press ESCAPE. 
PERFORM will respond by 
displaying "Record added" at the bottom of the 
screen. 
Select Add again and repeat the process of 
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adding information about each menu until you have 
described all the menus in the system. 


The fields in the top part of the form are 
filled in as follows: 


e 
Menu name -- DBMENU uses the menu name to find 
the menu you want when you make a selection 
that calls another menu. 
DBMENU never displays 
the menu name; it is only for its own use. 
Remember that the top-level menu must be named 
main. 


Line spacing -- A 1 in this field (the default) 
indicates that DBMENU is to single space the 
menu; a 2 indicates double spacing. 
Skip this 
field (accept the default) if you want a 
single-spaced menu. 


e 
Menu title -- This field contains the text that 
DBMENU will display at the top of the menu. 


Now go through the menus and add information 
about each selection that appears on each menu. 
Use 
the PERFORM Query (q) option to select the menu you 
want to add information to. 
If you press ESCAPE im- 
mediately after selecting Query, 
PERFORM will select 
all the menus. 
You can then go through the menus 
using the Next (n) and Previous (p) commands. 


When PERFORM displays the menu you want to add 
items to, select the Detail (d) option and then the 
Add (a) option. 
Add the information about the menu 
item, moving the cursor from field to field by 
pressing RETURN. 
You will only be entering informa- 
tion about one item at a time. 
When all the infor- 
mation is complete, press ESCAPE. 


The paragraphs below summarize the use of each 
of the fields in the Selection Section of the form. 


e 
Selection number -- The selection number is the 
number that appears to the left of each item on 
the menu. 
DBMENU displays choices in item- 
number order and allows you to select items 
from the menu by their item number. 
For 
single-spaced menus, you can have a maximum of 
28 items; double-spaced menus can have 14. 


Selection type -- An M in this field indicates 
that this selection calls another menu (named 
in the Next menu name field). 
A P indicates 
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that the sele9tion runs a program (named in the 
Program to execute field). 


Selection text -- This field contains the text 
that DBMENU displays to the right of the item 
number. 


Program to execute -- This field is used for 
item type P selections. 
It contains the 
operating system command that the selection ex- 
ecutes. 
This field is not filled in for type M 
menu items. 


Next menu name -- This field is used for type M 
selections. 
It contains the name of a menu 1n 


the selection list. 
This field is not filled 
in for type P menu items. 
DBMENU will issue an 
error message if you try to add the name of a 
menu that you have not already named for the 
menu system you are building. 
Because DBMENU 
performs this error checking as you are build- 
ing a menu system, it is necessary to define 
all your menu names before you fill in the 
selection section. 
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v. Using Your Menu System 


To 
~un DBMENU, give the command 


dbmenu 


DBMENU will display the main menu and wait 
fo~ 


you~ selection. 
It will 
p~ocess 
you~ menu selection 
as you have specified in the menus. 


You can 
~etu~n to the 
p~evious menu by 
p~essing 


the 
DEL key. 
You will exit 
f~om the menu 
p~ogram if 
you press DEL when the main menu is displayed. 
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VI. Modifying DBMENU 


To change the database name from menus, use an 
edi tor to change the database and file names in the 
text of the menus.sch (menus 
under MS-DOS), 
mitems.sch (mitems 
under MS-DOS), and 
men~form 
files. 
Then use DBBUILD to recompile the menus.sch 
(menus 
under MS-DOS), and mitems.sch (mitems 
under 
MS-DOS), files, and FORMBUILD to recompile menuform. 
Use the following command to run the new menu sys- 
tem, substituting the new database name you are us- 
ing for nevdb, the new menu filename for nevmenu, 
and the new items filename for nevitems. 
You may 
not have to change the menu and items filenames. 
If 
you do, be sure to change the master/detail state- 
ment in menuform. 


% dbmenu newdb [newmenu newitemsJ 
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The DBMENU schema is reproduced below for your con- 
venience. 


database menu 
file menuitem 


field 
imenuname type char length 10 
index dups 
{menu name, joins with menuname in menupages file} 


field 
itemnum 
type integer 
{the number of the item within a menu -- 
controls display order on screen; must be 
unique within each menu page group} 


field 
mtext 
type char length 60 
{the text of the menu} 


field 
mtype 
type char length 1 
{the type of the menu -- M for show another, 
P for run a program} 


field 
progname type char length 60 
{command line} 


field 
nextmenu type char length 10 
{the next menu to show, used if type = M} 


field mcomp type composite imenuname, 
itemnum 
index primary 
{used to ensure uniqueness of imenuname, itemnum 
combination} 
end 


database menu 


file 
menus 


field menuname 
type char 
length 10 index 
primary 
{name of the menu, must be unique in menupages 
file -- top level menu must be called "main"} 


field title 
type char 
length 60 
{title line on top of menu} 


field spacing type int 
{1 for single spacing, 
2 for double} 


end 
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I. 
Introduction 


DBSTATUS is a command-driven interactive 
language for optimizing the performance and modify- 
ing the structure of INFORMIX databases. 
You can 
use DBSTATUS to: 


• 
Add or delete indexes 


• 
Print a file's schema or status 


• 
Erase files or entire databases 


• 
Start or stop audit trails 


• 
Load or unload database files to or from 
operating system files 


The following stores database is assumed in the 
examples in this chapter. 


customers file 


cname 


Brooks, B. 
Field, 
W. 
Robin, R. 
Hart, 
W. 
Court, S. 
English, 
D. 


orders file 


oname 


Brooks, B. 
Brooks, B. 
Robin, R. 
Hart, 
W. 
Robin, R. 
Court, S. 
Court, S. 
English, D. 
English, 
D. 


address 


7 Apple Rd. 
43 Cherry Ln. 
12 Heather Ct. 
65 Lark Rd. 
56 Blossom Rd. 
82 Alpine Rd. 


item 


Work Bench 
Saw 
Work Bench 
File 
Hammer 
Saw 
File 
File 
Hammer 


balance 


10.50 
0.00 
23.45 
43.00 
0.00 
0.00 


quantity 


5 
1 
3 
3 
8 
3 
5 
1 
2 


Figure 1. The stores Database 
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II. 
Important Features 


II.A. 
Addition and Deletion of Indexes 


Since the number of indexes for a file affects 
performance and increases the amount of storage 
space the file requires, you should carefully con- 
sider which fields to index and when to create or 
remove indexes. 


INFORMIX performs operations based on indexed 
fields much more qUickly than operations on unin- 
dexed fields. 
However, unneeded indexes are un- 
desirable because INFORMIX takes some time to update 
the index file whenever you add or delete a record. 


In addition, indexes require disk space: 
typi- 
cally about a fifth of the space required by the 
data file, but in some cases even more disk space 
than the data file itself takes up. 


You can indicate which fields to index when you 
create a database. 
However, if you develop queries 
that require indexing additional fields, 
you can add 
indexes interactively from DBSTATUS with the 
ADD IN- 
DEX command. 
If you expect a great deal of update 
activity, you can remove some or all of the indexes 
with the DELETE INDEX command. 


II.B. 
Audit Trails 


An audit trail is a complete history of all ad- 
ditions, deletions, updates, and manipulations to 
your database. 
Since audit trails affect perfor- 
mance, storage, and the number of open files al- 
lowed, you should carefully consider when to start 
and stop audit trails on your database files. 
This 
subject is discussed in "When To Use Audit Trails" 
later in Section IV. 


You can start and stop audit trails with the 
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START AUDIT and STOP AUDIT commands. 
You can erase 


the contents of 
the.ope~ating system file that h:lds 


the audit trail with the ERASE AUDIT command. 
You 
can 
resto~e a database file 
f~om a backup copy and 
an audit 
t~ail with the RECOVER FILE command. 


II.C. 
File and Database Deletion 


INFORMIX uses several 
ope~ating system files 


for each database file, each of which must be delet- 
ed in order to delete a database file. 
The~efo~e, 


the ERASE DATABASE and ERASE FILE commands 
a~e 
p~o­ 


vided for 
you~ convenience. 


These commands delete all the 
ope~ating system 
files associated with the database 
o~ database file 
you specify. 


II.D. 
Database Schema and Status 


With the PRINT SCHEMA and PRINT STATUS com- 
mands, you can 
p~int the schema and status of a sin- 
gle file 
o~ of the 
enti~e database. 


II.E. 
Transferring Files 


With the LOAD, 
UNLOAD, 
LOAD ASCII, and UNLOAD 
ASCII commands, you can transfer files between IN- 
FORMIX databases, between computer systems, or 
between INFORMIX and 
othe~ applications programs. 
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II.F. 
Checking and Repairing Indexes 


The CHECK FILE and REPAIR FILE commands check 
the integrity of index files. 
These commands pro- 
vide most of the functions of the INFORMIX program 
BCHECK described in Section V of this chapter. 
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III. 
DBSTATUS Commands and Their Use 


If you run 
DBSTATUS from the Master Menu, the 
current database is assumed. 
If you run DBSTATUS 
from the operating system, you can specify the data- 
base name on the command line. 
If you do not speci- 
fy the database, 
DBSTATUS prompts for it, as shown 
below. 


_ dbstatus 


DBSTATUS Databaae Monitor 
INFORMIX veraion 3.2 
Copyright (C) 1981, 1982, 1983 Relational Database Systema, Inc. 
Software Serial Number RDS-000001 


Type 'h' if help is desired. 


Please select database. 
> stores 


SELECT DATABASE 


The database "stores" has been selected successfully. 


You can switch to a different database during a 
DBSTATUS session with the SELECT DATABASE command. 


DBSTATUS accepts commands in either uppercase 
or lowercase. 
You can abort any command by pressing 
the DELETE or RUBOUT key. 
When you issue a command 
and press RETURN, 
DBSTATUS echoes an acknowledgement 
to the screen. 
To end a DBSTATUS session, enter the 
word BYE or the character b and press RETURN. 
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III.A. 
PRINT SCHEMA 


PRINT SCHEMA [FOR file-name] 
[TO [PIPE] "file or program"] 


The PRINT SCHEMA command displays a file's 
schema, including information about audit trails and 
(in UNIX versions of INFORMIX) the permissions ap- 
plicable to the current user. 


If you do not specify a file, the schemas for 
all the files in the database are displayed. 
You 
can send the output of the PRINT SCHEMA command to 
an operating system file or, in UNIX versions, to 
the "standard input" of any program. 


> print schema 


PRINT SCHEMA 


database stores 


file customers 


fie Id cname 
field address 
field balance 


file orders 


field oname 
field item 
field quantity 


permission all 


type char 15 
type char 15 
type double 


permission all 


type char 15 
type char 15 
type integer 


> print schema for customers 


PRINT SCHEMA 


database stores 
file customers 
permission all 


field cname 
field address 
field balance 
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III.B. 
PRINT STATUS 


PRINT STATUS 
[FOR file-name] 
[TO [PIPE] "file or program"] 


The PRINT STATUS command displays general in- 
formation about the file, including the length of 
its records, the number of records, and the ex- 
istence and state of indexes and audit trails. 


If you do not specify a file, the status of all 
the files in the database is displayed. 
You can 
send the output of the PRINT STATUS command to an 
operating system file or, in UNIX versions, to the 
"standard input" of any program. 
(Note: Because 
DBSTATUS can alter the database, the examples shown 
may not agree with the sample database.) 


> print status 


PRINT STATUS 


database stores 


file customers 


data record length 
number of records 
number of indexes 
cname 
address 
balance 


file orders 


data record length 
number of records 
number of indexes 
oname 
item 
quantity 


10 


42 
6 
3 
duplicates not allowed 
duplicates allowed 
duplicates allowed 


36 
9 
3 
duplicates allowed 
duplicates allowed 
duplicates allowed 
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> print status for orders 


PRINT STATUS 


database stores 
file orders 


data record length 
number of records 
number of indexes 
oname 
item 
quantity 


III.C. 
ADD INDEX 


36 
9 
3 
duplicates allowed 
duplicates allowed 
duplicates allowed 


ADD INDEX FOR field-name 
[ALLOWING DUPS] 


You can use the ADD INDEX command for any type 
of field. 
No duplicate entries are allowed in the 
indexed field unless you add the ALLOWING DUPS (or 
ALLOWING DUPLICATES) clause to the command. 


Indexed CHARACTER fields may be no longer than 
120 characters. 


> print status for customers 


PRINT STATUS 


database stores 


file customers 


data record length 
number of records 
number of indexes 
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> add index for cname 


ADD INDEX 


There may be a pause while the new index is formed. 


An index has been added for the field "cname". 


> print status for customers 


PRINT STATUS 


database stores 


file customers 


data record length 
number of records 
number of indexes 
cname 


42 
6 
1 
duplicates not allowed 


> add index for balance allowing dups 


ADD INDEX 


There may be a pause while the new index is formed. 


An index has been added for the field "balance". 


> print status for customers 


PRINT STATUS 


database stores 
file customers 


data record length 
number of records 
number of indexes 
cname 
balance 


12 


42 
6 
2 
duplicates not allowed 
duplicates allowed 
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111.0. 
DELETE INDEX 


DELETE INDEX FOR field-name 


Use the DELETE INDEX command to remove an index 
from any field. 
You cannot use DELETE INDEX on a 
field that has no index. 


From DBSTATUS, you cannot delete the index on a 
primary key. 
Instead, you must specify a new pri- 
mary key using DBBUILD. 
See section II.E. of the 
DBBUILD chapter. 


) print status for customers 


PRINT STATUS 


database stores 
file customers 


data record length 
number of records 
number of indexes 
cname 
balance 


42 
6 
2 
duplicates not allowed 
duplicates allowed 


) delete index for cname 


DELETE INDEX 


The index for the field "cname" has been deleted. 
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> print status for customers 


PRINT STATUS 


database stores 


file customers 


data record length 
number of records 
number of indexes 
balance 


42 
6 
1 
duplicates allowed 


III.E. 
ERASE DATABASE 


ERASE DATABASE database-name 


The ERASE DATABASE command deletes all of the 
operating system files associated with the database. 


> erase database stores 


ERASE DATABASE 


The database that was erased was the current database. 
Please select a new current database. 
You may type BYE 
to exit from the program. 


Please select database. 
> bye 


Program over. 
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III.F. 
ERASE FILE 


ERASE FILE file-name 


The ERASE FILE command deletes the database 
file's data file, audit trail file (if there is one) 
and index file. 
It also removes the database file 
from the database dictionary. 


> erase file orders 


ERASE FILE 


The file "orders" has been erased. 


III.G. 
ERASE AUDIT 


ERASE AUDIT FOR file-name 


The ERASE AUDIT command erases the contents of 
the audit trail file for the specified database 
file. 
It does not remove the audit trail file it- 
self. 
After using the ERASE AUDIT command, the mes- 
sage "audit trail to audit-trail-name is turned off" 
will still appear when you use the PRINT STATUS com- 
mand. 


> erase audit for customers 


ERASE AUDIT TRAIL 


The audit trail fila "custaudit" has been erased. 
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> print status for customers 


PRINT STATUS 


database stores 
file customers 


data record length 
42 
number of records 
6 
number of indexes 
2 
cname 
duplicates not allowed 
balance 
duplicates allowed 
audit trail to "custaudit" is turned off 


III.H. 
RENAME FIELD 


RENAME FIELD old-field-name TO new-field-name 


The RENAME command changes the name of a field. 


After you use the RENAME command, modify the 
schema for the database file to reflect the change. 


Do not try to change a field name simply by 
editing the schema and recompiling it. 
If you do 
so, 
DBBUILD interprets your action as a request to 
delete an old field and add a new one. 
The data in 
the field will be lost. 
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> rename field cname to customername 


RENAME FIELD 


The field "cname" has been renamed "customername". 


> print schema 


PRINT SCHEMA 


database stores 
file customers 


field customername 
type character 
length 15 
field address 
type character 
length 15 
field balance 
type double 


file orders 


field oname 
type character 
length 15 
field item 
type character 
length 15 
field quantity 
type integer 


111.1. 
START AUDIT 


START AUDIT FOR file-name TO "path-name" 


The START AUDIT command turns on the audit 
trail switch in the database dictionary for the da- 
tabase file specified. 
If an audit trail for the 
specified file already exists on the pathname indi- 
cated, new audit trail information is appended to 
it. 
If there is no such audit trail, an operating 
system file for a new audit trail is created. 


After you give the START AUDIT command, make a 
backup copy of your database file. 


Audit trail information is stored in a special 
format. 
See "Audit Trail File Formats," later in 
this chapter. 


The example below shows that a line has been 
added to the PRINT STATUS output for the file 
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customers. 
Once you create an audit trail for a 
file, its status is always given when you use the 
PRINT STATUS command. 


> start audit for customers to "custaudit" 


START AUDIT 


The audit trail for the database 
file "customers" has been turned on. 


The audit trail information will 
be written to "custaudit". 


> print status for customers 


PRINT STATUS 


database stores 


file customers 


data record length 
42 
number of records 
6 
number of indexes 
2 
cname 
duplicates not allowed 
balance 
duplicates allowed 
audit trail to "custaudit" is turned on 


III.J. 
STOP AUDIT 


STOP AUDIT FOR file-name 


The STOP AUDIT command turns off the audit 
trail switch in the database dictionary for the 
specified database file. 
Subsequent modifications 
to the database file are not recorded in the audit 
trail. 


Stopping an audit trail' does not erase the con- 
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tents of the audit trail file. 
If you start the au- 
dit trail once again, subsequent transactions are 
appended to the old audit trail file. 
If you want a 
new audit trail file, stop the existing audit trail, 
erase the contents of the audit trail file with the 
ERASE AUDIT command, and then use the START AUDIT 
command. 


> print status for customers 


PRINT STATUS 


database stores 
file customers 


42 
6 
2 
duplicates not allowed 
duplicates allowed 
"custaudit" is turned on 


data record length 
number of records 
number of indexes 
cname 
balance 
audi t trail to 


> stop audit for customers 


STOP AUDIT 


The audit trail for the database 
file "customers" has been turned off. 


> print status for customers 


PRINT STATUS 


database stores 
file customers 


data record length 
42 
number of records 
6 
number of indexes 
2 
cname 
duplicates not allowed 
balance 
duplicates allowed 
audit trail to "custaudit" is turned off 
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III.K. 
RECOVER FILE 


RECOVER FILE file-name 


The RECOVER FILE command restores a database 
file from its audit trail and a backup copy in the 
event of a system failure. 
Make the backup copy of 
the database immediately after you have given the 
START AUDIT command. 
------ 


Once you have recovered the file back it up 
again. 
Then use ERASE AUDIT to remove the contents 
of the audit trail file, restart the audit trail, 
and make a new backup. 
The first backup is for 
safety, the second is to be used with the audit 
trail to restore the file in case of another system 
failure. 


> recover file customers 


RECOVER FILE 


There may be a pause while 
the database file is recovered. 


The database file "customers" has been recovered 
from the file "custaudit". 


III.L. 
LOAD 


LOAD file-name 
FROM "file" 


LOAD file-name FROM PIPE "program" 


The LOAD command fills the database file speci- 
fied by file-name with records from the operating 
system file specified by "file" or "program". 
The 
length of each record in the operating system file 
must be one byte greater than the records of the da- 
tabase file. 
The last byte in the operating system 
file records must be the newline character, binary 
10 in the ASCII code. 
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Other than this newline character, the lengths, 
positions, and types of the fields in the operating 
system file must be identical to the fields speci- 
fied for the database file. 
You can use the PRINT 
SCHEMA command to check the byte lengths and posi- 
tions of the fields in the database file. 


Under UNIX, you can use the PIPE option to load 
data generated by another program. 
The PIPE option 
is particularly useful when there is not enough 
storage room for both the database file and the file 
being loaded. 
If the database is being loaded from 
a tape, you can specify a program which can read the 
tape, and its standard output will be used as the 
input to the LOAD command. 


The example below. shows the simpler case where 
a database file is being loaded from an operating 
system file. 


> load customers from "custdata" 


LOAD 


There may be a pause while the file is loaded. 


There were 6 records loaded from "custdata". 


If the data is being loaded from a remote 
device, such as a tape drive, give the command as 
follows. 


> load customers from pipe "dd if=/dev/rmtO" 
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III. M. 
UNLOAD 


UNLOAD file-name TO "file" 


UNLOAD file-name TO PIPE "program" 


The UNLOAD 'command copies the database file 
specified by file-name to an operating system file 
in the format expected by the LOAD command. 
Specif- 
ically, the records are written with a newline end- 
of-record marker. 
If there are n records in the da- 
tabase file and the records are m bytes long, the 
operating system file will be (n x (m 
+ 1» 
bytes 
long. 


If all of the fields are CHARACTER fields, the 
unloaded file can be sent to a printer. 
Operating 
system utilities designed to work with text editor 
files may be used on the unloaded file. 


Under UNIX, you can use the PIPE option to un- 
load database files to programs which may be writing 
to a tape, some other device, or processing the file 
in a special way. 
If you are storing a large part 
of a database for archival purposes, a data compac- 
tion program can be used with the PIPE option to 
shrink the data as it comes out of the database and 
expand it as it goes back in. 


The example below shows the simple case where a 
database file is being sent to an operating system 
file. 


> unload customers to "custdata" 


UNLOAD 


There may be a pause while the file is unloaded. 


There were 6 records unloaded to "custdata". 


If the database file is being unloaded to a re- 
mote device, such as a tape drive, give the command 
as follows. 
> unload customers to pipe "dd of=/dev/rmtO" 
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III.N. 
LOAD ASCII and UNLOAD ASCII 


LOAD ASCII file-name FROM "file" 


LOAD ASCII file-name 
FROM PIPE "program" 


UNLOAD ASCII file-name TO "file" 


UNLOAD ASCII file-name TO PIPE "program" 


The LOAD ASCII and UNLOAD ASCII commands per- 
form very similar functions to LOAD and UNLOAD, but 
differ in three important ways: 


e 
The ASCII commands move all data including 
numbers in ASCII form. 
This greatly simplifies 
the procedure for moving data from computer to 
computer or from programs to files. 


The ASCII commands do not require fixed-length 
records and fields. 


The ASCII commands require that fields be 
separated by a standard delimiter and that 
records be ended With a line feed. 
INFORMIX 
files unloaded using the UNLOAD ASCII command 
automatically conform to this format. 
Unless 
you specify a different character by using the 
DBSTATUS DELIMITER command, 
LOAD ASCII and UN- 
LOAD ASCII expect a vertical bar (I) to delimit 
fields. 


LOAD ASCII accepts files whose records are ter- 
minated with a line feed or a line feed followed by 
a RETURN. 
Records created by INFORMIX are terminat- 
ed by a line feed alone. 
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111.0. 
UNLOCK FILE 


UNLOCK FILE file-name 


Some INFORMIX commands automatically lock data- 
base files while they work, and unlock the files 
when they are finished. 
If one of these commands 
aborts without having unlocked a file, you can use 
the UNLOCK FILE command. 


> unlock file offices 


UNLOCK FILES 


> File "offices" unlocked. 


III.P. 
DELIMITER 


DELIMITER "one_character" 


DELIMITER control_key_ascii_code_number 


INFORMIX uses a vertical bar (i) to delimit 
fields in database files. 
With the DELIMITER com- 
mand you can change this default to any other char- 
acter. 
If you define another character as the delim- 
iter, all files loaded by the ASCII LOAD command 
must use this character as the delimiter and in no 
other capacity within the file. 
All files unloaded 
with the ASCII UNLOAD command use the delimiter you 
have defined. 
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III.Q. 
CHECK FILE and REPAIR FILE 


CHECK FILE file-name 


REPAIR FILE file-name 


These commands provide the functions of BCHECK 
from within DBSTATUS. 
CHECK FILE compares the index 
(.idx) file to the data (.dat) file to see whether 
the two are consistent. 
If they are not, REPAIR 
FILE deletes the damaged indexes and rebuilds them. 


III.R. 
SELECT DATABASE 


SELECT DATABASE database-name 


The SELECT DATABASE command changes the current 
database. 
You can use it to switch databases 
without leaving DBSTATUS. 


The SELECT DATABASE command can be abbreviated 
as SELECT DB. 
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> select database stores 


SELECT DATABASE 


The database "stores" has been selected successfully. 


> print schema 


PRINT SCHEMA 


database stores 
file customers 
permission all 


field cname 
type char 15 
field address 
type char 15 
field balance 
type double 


file orders 
permission all 


field oname 
type char 15 
field item 
type char 15 
field quantity 
type integer 


III. S. 
The HELP Command 


HELP 


The HELP command provides a list of the com- 
mands available in DBSTATUS. 
> help 


HELP 
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> help 


HELP 


This or any command can be terminated by 
pressing RUBOUT or DELETE. 


Commands: 


ADD INDEX FOR field_name 
[ALLOWING DUPS] 
BYE 
DELETE INDEX FOR field name 
ERASE AUDIT FOR file name 
ERASE DATABASE database name 
ERASE FILE file name 
- 
HELP 
- 
RECOVER FILE file name 
RENAME FIELD old field name TO new field name 
SELECT DATABASE database name 
START AUDIT FOR file .name TO "audit trail name" 
STOP AUDIT FOR file name 
- 
PRINT SCHEMA [FOR fIle name] 
[TO [PIPE] "regular file name"] 
PRINT STATUS [FOR file name] 


[TO [PIPE] "regular file name"] 
UNLOCK FILE file_name- 
- 


UNLOAD file name TO [PIPE] "regular file name" 
LOAD file_name FROM [PIPE] "regula()ile=:name" 


DELIMITER "one character" 
DELIMITER control key number 
UNLOAD ASCII file-name TO [PIPE] "regular file name" 
LOAD ASCII file name FROM [PIPE] "regular=:file=:name" 
CHECK FILE file-name 
REPAIR FILE file_name 
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III. T. 
The BYE Co-mand 


BYE 


The BYE command closes any open files and ter- 
minates the DBSTATUS session. 


> bye 


BYE 


Program over. 
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IV. 
Recovery from Hardware and Software Failure 


IV.A. 
When To Use Audit Trails 


The existence of audit trails affects perfor- 


mance, storage, and the number of open files al- 
lowed. 
Therefore, you might want to stop audit 
trails at certain points, for example, before you 
perform automatic updates with a program that can be 
easily rerun should the computer system fail. 


Audit trails slow INFORMIX slightly because 
each transaction to a database is recorded in an au- 
dit trail file. 
They can consume a great deal of 
storage space after many transactions. 


Finally, the existence of audit trails de- 
creases the number of database files that INFORMIX 
can open simultaneously. 
Without an audit trail, 
each open database file requires that two operating 
system files (the .dat file and the .idx file) 
be 
opened. 
With an audit trail, a third operating sys- 
tem file is opened whenever the database file is 
used. 
For more information about limits on the 
number of files that can be open simultaneously, see 
"Number of Open Files" in the Introduction to this 
manual. 


IV.B. 
Audit Trail Protocols 


When you start an audit trail with the START 
AUDIT command, 
you specify its location by giving a 
full path name. 
The audit trail file should be on a 
physical device other than the one that holds the 
data so that a system failure affecting the device 
that holds the data will not also damage the audit 
trail. 


If the computer system has more than one hard 
disk, the audit trails could be written to one of 
the disks not containing the data. 
A removable 
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medium, such as a floppy disk, is preferable if you 
can set up a file system on it. 
If a floppy disk is 
attached to the system, it should be mounted to the 
pathname used by the audit trails. 


You cannot put an audit trail file on a tape 
drive. 


To use audit trails, make a backup copy of your 
database after you have given the START AUDIT com- 
mand but befOre you make any changes to the data- 
base. 
Once you have started the audit trail and 
have made a backup, you are ready to work with the 
database. 


Erase and restart the audit trail files whenev- 
er you make a complete backup of the device contain- 
ing the .dat and .idx files. 
If a system failure 
does occur, you can use the audit trail to update 
the database from the time of the last backup to the 
time the failure occurred.- 


IV.C. 
Audit Trail File For.ats 


The records in an audit trail file contain a 
9-byte header, the data record that was the SUbject 
of the transaction, and the ASCII newline character 
(binary 10). 
The 9-byte header is composed of the 
following information: 


byte 1 


The character A if the record is being added, D if 
it is being deleted, R if it is the old (read) ver- 
sion of a record being updated, and Wif it is the 
new (written) version of a record being updated. 


bytes 2 through 5 


A 4-byte representation of the date and time. 
Under 
UNIX, this number is the number of seconds since 
January 1, 1970. 
The UNIX routines time(2} and 
ctime(3) can be used to resolve this number into a 
date and time. 
The following table shows the compo- 
sition of this number under MS-DOS. 
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year 
6 bits represent the year - 1980 
month 
4 bits 1-12 
day 
5 bits 1-31 
hour 
5 bits 0-23 
minute 
6 bits 0-59 
second 
6 bits 0-59 


bytes 6 and 7 


Under UNIX, a 2-byte integer representing the pro- 
cess ID of the process that performed the transac- 
tion. 
Under MS-DOS, zero. 


bytes 8 and 9 


Under UNIX, a 2-byte integer representing the user 
ID of the user who performed the transaction. 
Under 
MS-DOS, zero. 


IV.D. 
Recovery Procedures 


If data integrity is lost due to hardware or 
software failure, load the most recent backup of 
your database. 
Usually, you will then give the RE- 
COVER FILE command. 


The backup copy must be in the exact state the 
database was in when the audit trail was started. 
If this is not the case, the unique record 
identifiers of the records in the database will not 
match their counterparts in the audit trail file. 
INFORMIX will display a warning message indicating 
that audit trail recovery deletions could not be 
done. 


However, in some cases you may not want to use 
the entire audit trail file. 
You can choose to run 
a portion of the audit trail file against the backup 
file of your database. 


For example, if a user performed incorrect 
modifications, you can use a subset of the audit 
trail file to replay all transactions to the data- 
base except those performed by that user. 
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The procedure for creating a subset of an audit 
trail file follows. 


First, save a copy of the audit trail file 
under a different name. 
Then, create a database 
file with DBBUILD and load the audit trail file into 
it. 
This database file must include fields for the 
information in the 9-byte header described in the 
previous section of this chapter, as well as the 
fields in the database file you are recovering, in 
the same order as in its schema. 
A schema for a da- 
tabase file into which you might load an audit trail 
file is shown here. 


database stores 


file auditfix 


field op_type 
type char 1 
field date time 
type long 
field pS_id 
type integer 
field usr id 
type integer 
field rec-id 
type long 
field cname 
type char 15 
field address 
type char 15 
field balance 
type money 


end 


Once you have loaded the audit trail file into 
this new database file, you can modify it using IN- 
FORMER, ENTER2, or PERFORM. 
To delete the transac- 
tions performed by a user, you would delete all the 
records with the appropriate user id. 


Then use the UNLOAD command to put the audit 
trail information back into an operating system file 
with the same name as the original audit trail file. 


Now you can run the modified audit trail file 
against the backup copy of your database. 


Using this procedure, you can recover from al- 
most ~ny situation without custom programming. 
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v. 
BCHECK 


The SCHECK program is not part of DSSTATUS. 
You call it directly from the operating system. 
(From DSSTATUS, you can use the CHECK FILE and 
REPAIR FILE command to accomplish most of the func- 
tions that SCHECK provides.) 


SCHECK checks and repairs index files. 
It com- 
pares an index (.idx) file to a data (.dat) file to 
see whether the two are consistent. 
If they are 
not, it asks you whether to delete and rebuild the 
corrupted indexes. 


In the example below, 
SCHECK is run on the 
customers file. 


~ bcheck customers 


BCHECK 
C-ISAM B-tree Checker version 1.04 
Copyright (C) 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-R000001 


C-ISAM File: customers 


Checking dictionary and file sizes. 
Checking data file records. 
Checking indexes and key descriptions. 
Index 1 
= unique key 
(0,4,2) 
1 index node(s) used -- 1 index b-tree level(s) used 
Index 2 = unique key 
(4,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 
Index 3 = duplicates 
(19,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 
Index 4 = duplicates 
(34,8,3) 
1 index node(s) used -- 1 index b-tree level(s) used 
Checking data record and index node free lists. 
6 index node(s) used, 0 free -- 6 data record(s) used, 0 free 


In this example, 
SCHECK found no errors. 
(Note 
that for each index, 
SCHECK prints a group of 
numbers. 
There may be up to eight groups of numbers 
for each index. 
These numbers indicate the position 
of the key in each record.) 
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SCHECK can also be used with any of the follow- 
ing options: 


-i 
check index file only 


-1 
list entries in b-trees 


-n 
answer no to all questions 


-y 
answer yes to all questions 


The syntax for using these options is 


:c bcheck {-i} 
:c bcheck {-I} 
file-name 


:c bcheck {-n} 
:c bcheck {-y} 


Unless you use the -n or -y option, 
SCHECK is 
interactive and waits for you to respond to each er- 
ror it finds. 
Use the -y option with caution. 
SCHECK should not be run using the -y option if it 
is the first time you are checking the files. 


Here is a sample run in which SCHECK finds some 
errors. 
The -n option means that each question 
SCHECK asks is automatically answered "no." 
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% bcheck -n customers 


BCHECK 
C-ISAM B-tree Checker version 1.04 
Copyright (C) 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-R000001 


C-ISAM File: customers 


Checking dictionary and file sizes. 
Checking data file records. 
Checking indexes and key descriptions. 
Index 1 = unique key 
(0,4,2) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 3 bad data record(s) 
Delete index ? no 


Index 2 = unique key 
(4,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 3 bad data record(s) 
Delete index ? no 


Index 3 = duplicates 
(19,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 3 bad data record(s) 
Delete index ? no 


Index 4 = duplicates 
(34,8,3) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 3 bad data record(s) 
Delete index ? no 


Checking data record and index node free lists. 


ERROR: 3 missing data record(s) 
Fix data record free list ? no 


6 index node(s) used, 0 free -- 3 data record(s) used, 3 free 


In this case, the corrupted indexes must be 
deleted and rebuilt. 
Use the -y option to answer 
yes to all questions asked by SCHECK as follows: 
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• bcheck -y customers 


BCHECK 
C-ISAM B-tree Checker version 1.04 
Copyright (C) 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-R000001 


C-ISAM File: customers 


Checking dictionary and file aizes. 
Checking data file records. 
Checking indexes and key descriptions. 
Index 1 = unique key 
(0,4,2) 
1 index node(s) used -- 1 index b-tree level(s) uaed 


ERROR: 3 bad data record(s) 
Delete index ? yes 


Remake index ? yes 


Index 2 = unique key 
(4,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 3 bad data record(s) 
Delete index ? yes 


Remake index ? yes 


Index 3 = duplicates 
(19,15,0) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 3 bad data record(s) 
Delete index ? yes 


Remake index ? yes 


Index 4 = duplicates 
(34,8,3) 
1 index node(s) used -- 1 index b-tree level(s) used 


ERROR: 3 bad data record(s) 
Delete index ? yes 


Remake index ? yes 


Checking data record and index node free lists. 


ERROR: 3 missing data record(s) 
Fix data record free list? yes 


Recreating data record free list. 
Recreating index 4. 
Recreating index 3. 
Recreating index 2. 
Reoreating index 1. 
6 index node(s) used, 0 iree -- 3 data record(s) used, 3 free 
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VI. 
Appendix - Error "Messages 


error 4000: 


The current command is not valid. 
Please try again. 


The commands of DBSTATUS, along with their legal ab- 
breviations, are listed in the 
DBSTATUS chapter, as 
well as in the interactive HELP command. 
One of the 
legal commands must be used. 


error 4001: 


The field name specified has been used previously 
for the database specified. 


error 4002: 


The field name FIELD-NAME is currently being used as 
a file name in the database system DATABASE-NAME. 


File names and field names must all be unique. 
The 
DBSTATUS interpreter checks the names of all of the 
other files and fields in the database before it al- 
lows the renaming of a field. If the new name al- 
ready exists in the database, 
DBSTATUS must disallow 
this renaming to the same name. To correct this 
situation, either choose another name or rename the 
field that is in conflict with the new name. 


error 4003: 


This identifier exceeds the maximum length allowed 
which 
is50~ 


The name of the database, the files and the fields 
are all considered identifiers. Any identifier may 
be up to 50 characters in length. In the case of 
fields, all 50 of these characters are significant 
in comparisons. 


error 4004: 


Field names must be between two and fifty characters 
long. Rules for identifiers are described in the 
DBBUILD chapter. 
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error 4005: 


There is not enough room in the string table to add 
the field name FIELD-NAME. 


Part of the database dictionary is a list consisting 
of all the file names and field names in the data- 
base. 
When an INFORMIX program is read into memory 
to be executed, the entire database dictionary, in- 
cluding this list, must be read into memory as well. 
The list is stored in what is known as a "string 
table." The programs allocate memory for the string 
table dynamically, so that the amount of memory 
available to hold the string table varies from one 
type of machine to the next, and from one program to 
the next. 
If this limit becomes a problem, it is 
possible to provide extra room by renaming fields 
with shorter names. 


error 4006: 


An unidentifiable character sequence or a non- 
printing character has been found. 


There are certain characters that can be transmitted 
to computers that are not visible on computer termi- 
nals. They are generated by holding down the CONTROL 
key and striking an ordinary character, much like a 
capital letter is generated by holding down the 
SHIFT key. 
These characters are usually used to get 
the computer to perform various acts. For example, 
many operating systems use the CONTROL-D sequence to 
indicate the end of a user's session at the termi- 
nal. However, these characters have no place in com- 
puter programs, such as the files that hold DBBUILD 
file descriptions. Most text editors have facilities 
for visualizing the invisible control characters, 
and allowing the user to eliminate them from the 
program. 


error 4007: 


A quote has been found for which there is no match- 
ing quote. 


When quoted strings are used in INFORMIX interactive 
languages, they must begin and end on the same line. 
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error 4008: 


An illegal double has been 
ent~red. The maximum 
number of significant digits for a double is 15. The 
number of characters used to express the precision 
of a double precision floating point number is lim- 
ited by INFORMIX to 15. 


error 4010: 


The field FIELD-NAME could not be found for the da- 
tabase system DATABASE-NAME. 


An identifier was typed to DBSTATUS where a field 
name was expected. 
Although DBSTATUS searched the 
database data dictionary, the identifier typed could 
not be found. 
The PRINT SCHEMA command can be used 
to print the database schema, to verify the ex- 
istence and proper spelling of identifiers such as 
file names and field names. 


error 4011: 


This quoted string exceeds the maximum length al- 
lowed which is 50. 


When quoted strings are used in INFORMIX interactive 
languages, they must be less than or equal to 50 
characters in length. 
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error 4012: 


An internal system error has occurred. 


error 4013: 


An illegal integer has been entered. 
INFORMIX in- 
tegers must be in the range -32760 through +32760. 


error 4015: 


The database DATABASE-NAME could not be found. 
Please try again. 


When DBSTATUS is run, the database to be examined 
must be in the current directory. This means that 
before DBSTATUS is run, the operating system command 
to list files must reveal the databases of interest 
and they must contain data. 
These files all begin 
with the first four characters of the database name. 


error 4016: 


The file FILE-NAME could not be found. 
Please try 
again. 


An identifier was typed to DBSTATUS where a file 
name was expected. 
Although DBSTATUS searched the 
database data dictionary, the identifier could not 
be found. The DBSTATUS program can be used to print 
the database schema, to verify the existence and 
proper spelling of identifiers such as file names 
and field names. 
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error 4017: 


An attempt was made to add a duplicate value to an 
index file for which no duplicates was specified. 


When a file is loaded with information using the 
DBSTATUS LOAD command, the data is checked as it 
enters the file. If an index exists for the file 
demanding uniqueness, then this uniqueness is en- 
forced at the time the data is loaded. This error 
message indicates that a duplicate entry was at- 
tempted for a file that had a unique index. 
This 
problem could be caused by unexpected duplicate data 
in a file that was thought to have unique informa- 
tion. It could also be due to the construction of an 
index where uniqueness was inadvertently requested. 
Uniqueness is the default. The ALLOWING DUPS phrase 
must be used in the DBSTATUS ADD INDEX command if 
the enforcement of uniqueness is not desired. This 
error could also be due to a misalignment of infor- 
mation in the file being loaded. If the length of 
the records in the file being loaded does not 
correspond correctly with the length of the record, 
data could get loaded into the wrong fields. If this 
is suspected, the alignment of the file record and 
its fields should be checked against the record and 
its fields. 


error 4019: 


The file FILENAME cannot be opened. 


This situation could occur if a file that is being 
requested cannot be found in the operating system's 
current file directory, or if the user does not have 
access to the file. If the file is a file that has 
been created by the user, such as a load file, then 
DBSTATUS should be exited and the operating system 
should be used to examine the contents of the 
current directory. If the missing file appears to be 
part of the database system that has been damaged or 
destroyed somehow, the database should be regenerat- 
ed if possible. 
This can be done by unloading the 
files, erasing the database, recompiling the files, 
and reloading them. If the files cannot be reloaded 
successfully, the database should be restored from 
the last tape backup. 
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error 4020: 


The file FILENAME cannot be read. 


This situation could occur if a file that is being 
requested cannot be found in the operating system's 
current file directory. If the file is a file that 
has been created by the user, such as a load file, 
then DBSTATUS should be exited and the operating 
system should be used to examine the contents and 
permissions of the current directory. 
If the miss- 
ing file appears to be part of the database system 
that has been damaged or destroyed somehow, the da- 
tabase should be regenerated if possible. 
This can 
be done by unloading the files, erasing the data- 
base, recompiling the files, and reloading them. If 
the files cannot be reloaded successfully, the data- 
base should be restored from the last tape backup. 


error 4021: 


An error occurred during an attempt to write to the 
file FILENAME. 


This situation could occur if a file that is being 
requested cannot be found in the operating system's 
current file directory. If the file is a file that 
has been created by the user, such as a load file, 
then 
DBSTATUS should be exited and the operating 
system should be used to examine the contents of the 
current directory. If the missing file appears to be 
part of the database system that has been damaged or 
destroyed somehow, the database should be regenerat- 
ed if possible. 
This can be done by unloading the 
files, erasing the database, recompiling the files, 
and reloading them. If the files cannot be reloaded 
successfully, the database 
shoul~ be restored from 
the last tape backup. 


error 4024: 


There is no data in the system. 


If DBSTATUS is asked to unload a file and discovers 
there are currently no records in the file, this 
message will be generated to indicate this. 
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error 4025: 


The field FIELD-NAME has not been defined. 


An identifier was typed to DBSTATUS where a field 
name was expected. 
Although DBSTATUS searched the 
database data dictionary, the identifier typed could 
not be found. 
The DBSTATUS program can be used to 
print the database schema, to verify the existence 
and proper spelling of identifiers such as file 
names and field names. 


error 4026: 


No index has been created for FIELD-NAME. 


If a DELETE INDEX command is given to DBSTATUS, but 
no index currently exists for the index in question, 
this message will be generated. 


error 4027: 


The file FILE-NAME cannot be found. 


See error 4016. 


error 4029: 


The index for field FIELD-NAME already exists. 


A field may only be indexed once. If an ADD INDEX 
command is issued for a field that is already in- 
dexed, then this message will be generated. 


error 4030: 


The database DATABASE-NAME does not exist. 


See error 4015. 


error 4031: 


There is no audit trail for the specified file. 


When the ERASE AUDIT TRAIL command is given, the au- 
dit trail that is to be erased must exist. 
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error 4032: 


The LOAD input file has incorrect format. 


The LOAD command determines the length of the 
records in the load file based upon the length of 
the records in the file into which it is loading in- 
formation. If it finds an incomplete record at the 
end of the file, this message is printed. This might 
be due to a miscalculation of the length of the 
records or the length of the records in the load 
file. 
Load files must contain records that are all 
the same length. In addition, the records must con- 
tain exactly the number of bytes that are in the 
file that is being loaded, as well as an additional 
newline character at the end of each record. This 
newline character is discarded during the loading 
process. 


error 4033: 


Indexes may not be created for character fields 
which are longer than 120 bytes. 


The limit on the size of a field that can be indexed 
is 120 characters, in the standard version of INFOR- 
MIX. 


error 4034: 


The last record of the file could not be read in 
order to set a unique id. 


error 4035: 


Permission to do this operation is not granted be- 
cause you do not have CONTROL access to the file. 
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I. 
Introduction 


The INFORMIX library routines allow C applica- 
tions programmers to manipulate the data in the da- 
tabase from their own custom-built programs. 
Rou- 
tines are available to perform addition and deletion 
of data to the database files, as well as reading of 
data utilizing the fast B-Tree indexes maintained by 
INFORMIX. 


A database may be selected for processing using 
the DBSELECT routine. 
This routine may then be used 
to select permanent files for processing. 
Up to five 
through eight files, depending on the number of au- 
dit trails, can be opened for processing at the same 
time. 
Memory use can also affect the number of 
files you can open. 
This routine may also be used 
to close files and the database. 
All files and the 
database should be closed before processing is ter- 
minated. 


Before a file is manipulated, a "view" of that 
file must be established using DBSETFILEVIEW or 
DBSTRUCTVIEW. 
These routines accept a sequence of 
field names, and build a template of the file with 
those names. 
Subsequent transactions on that file, 
such as those performed by the DBFIND and DBADD rou- 
tines, will be performed on that view of the data. 
This provides "data independence" for the applica- 
tions program. 
If the fields are added to the file 
that is being processed, the applications program 
need not be changed. 
The use of DBSETFILEVIEW or 
DBSTRUCTVIEW also makes programs independent of 
changes in the ordering of the fields. 
The only 
changes to the database structure that could require 
changes to applications programs are the deletions 
of fields that are required by the program, changes 
in the names of the fields that are used by the pro- 
gram, or changes in the length of these fields. 


On UNIX systems, 
DBLOCK and DBUNLOCK allow the 
programmer to provide for dynamic concurrency con- 
trol on the file level. 


The library routines are designed to give the 
applications programmer the power to perform the 
data manipulation operations of ENTER2. 
Thus, if 
these turn-key programs are not suitable for specif- 
ic needs, the database can be accessed easily in a 
very customized fashion, using the library. 
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II. 
The INFORMIX ALL-II Routines 


II.A. 
Header File dbio.h 


The header file dbio.h contains C "defines" 
that are to be used in the calls to the routines in 
the Applications Language Library (ALL-II). 
These 
defines are used as flags to indicate to the rou- 
tines the desires of the programmer. 
For example, 
the DBSELECT command expects to receive DBOPEN, 
DBCLOSE, FILEOPEN, or FILECLOSE as the value of its 
flag parameter. 
Based on this value the routine can 
determine if the programmer wants to open or close a 
file or a database. 


This file must be included in all applications 
programs. 
The line 


#include <dbio.h> 


will accomplish this. 
The dbio.h file should be in- 
stalled in the /usr/include directory. 
The file is 
shipped with INFORMIX, and is reproduced below for 
your convenience. 
. 


/* 
**************************************************** 
** Copyright(c) 1981, 1982, 1983, 1984 by Relational 
* Database Systems, Inc. 
****** INFORMIX -- Relational Database Management System 
** Title: 
***************************************************** 
*/ 


#define DBOPEN 
1 
#define DBCLOSE 
2 
#define FILEOPEN 
3 
#define RELOPEN 
3 
#define FILECLOSE 
4 
#define RELCLOSE 
4 


#define OPENMASK 
OxOOff 
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#define EXCLUSIVE 
Ox0100 
#define READONLY 
Ox0200 
#define READWRITE . 
OxOOOO 


#define COMPARISON 1 
#define FIRST 
2 
#define LAST 
3 
#define NEXT 
4 
Hdefine PREVIOUS 
5 
#define EQUAL 
6 
#define GTEQ 
7 
_--Hdefine GREATER 
8 
Hdefine CURRENT 
9 
Hdefine LOCK 
0400 


/* values passed to dbselfield() */ 
Hdefine ACCKEYED 
0 
Hdefine ACCPRIMARY 
1 
Hdefine ACCSEQUENTIAL 
2 


( 
'. 


struct dbview 
{ 
char *vwname; 
int vwstart; 
int vwtype; 
int vwlen; 
}; 


Hdefine CHARTYPE 
Hdefine INTTYPE 
Hdefine INTSIZE 
Ide fine LONGTYPE 
Hdefine LONGSIZE 
Hdefine DOUBLETYPE 
Hdefine DOUBLESIZE 
Hdefine FLOATTYPE 
Hdefine FLOATSIZE 
Hdefine SERIALTYPE 
Hdefine SERIALSIZE 
Hdefine DATETYPE 
Hdefine EDATETYPE 
Hdefine YDATETYPE 
#define DATESIZE 
#define MONEYTYPE 
Hdefine MONEYSIZE 
Hdefine COMPOSTYPE 


#define CENTS(d) 
Hdefine DOLLARS( c) 
#ifndef ROUND 
Hdefine ROUND(c) 
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/* name of attribute*/ 
/* offset in view*/ 
/* type of attribute*/ 
/* length in bytes*/ 


o 
1 
2 
2 
4 
3(sizeof(double» 
4(sizeof( float» 
(Ox0100 
+ LONGTYPE) 
LONGSIZE 
(Ox0200 + LONGTYPE) 
(Ox0300 
+ LONGTYPE) 
(Ox0400 
+ LONGTYPE) 
LONGSIZE 
(Ox0500 
+ DOUBLETYPE) 
DOUBLESIZE 
( -1) 


(round(d*100.0» 
(c/100.0) 


(round(c» 
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#endif 


/* values returned 
#define NOINDEX 
#define NODUPS 
Idefine DUPS 


by dbindex() */ 
o 
1 
2 


/* permission flags */ 


#define PERM READ 
#define PERM-UPDATE 
#define PERM-INSERT 
#define PERM-DELETE 
#define PERM-CONTROL 
#define PERM-ALL 
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II.B. 
DBSELECT 


Call Format: 


dbselect(flag,name) 
int flag; 
char *name; 


Parameters: 


Flag is DBOPEN, 
DB~SE, 
FILEOPEN, or FILECLOSE 
(see the dbio.h innlude file) and name is a 
pointer to either the database name or the file 
name. 


Description: 


DBSELECT is used to open and close databases 
and files. 
Only one database can be open at a 
time. 
Up to five through eight permanent 
files, depending on the number of audit trails, 
can be open at the same time. 


You can AND READONLY, EXCLUSIVE, or READWRITE 
to the FILEOPEN flag. 
For example, 
FILEOPEN+EXCLUSIVE will open a file with ex- 
clusive access. 


Error Codes: 


o - call executed successfully 


6000 - tried to close an unopened file or database 


6001 - the database or file does not exist 


6002 - tried to open more than one database 


6004 - tried to open a file when no database was open 


6014 - no such flag value 


6024 - memory allocation error, out of memory 


6031 - access permission denied 


-1 - internal error 
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II.C.!. 
DBSETFILEVIEV 


Command Format: 


dbsetfileview(filename, fieldlist, n) 
char *filename; 
char *fieldlist[]; 
int n; 


Parameters: 


Filename 
is a pointer to the file name, 
fieldlist is an array of pointers to field 
names, and n is the number of fields in the 
list. 


Description: 


DBSETFILEVIEW is used to select fields from the 
file referred to by the filename parameter of 
this call. 
The list of fields will define the 
record to be used by future ALL calls. 
Any 
fields within the file filename may be speci- 
fied in any order. 


Error Codes: 
o - call executed successfully 


6005 - a field cannot be found 


6006 - filename has not been opened 


6024 - memory allocation error, out of memory 


6025 - tried to open a file more than once 


6031 - access permission denied 


6051 - composite field names are not allowed in 
dbview 


-1 - internal error 
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II.C.ii. 
DBSTRUCTVIEV 


Command Format: 


dbstructview(filename,fieldlist,n) 
char *filename; 
struct dbview *fieldlist; 
int nj 


Parameters: 


Filename is a pointer to the file name, 
fieldlist is a pointer to an array of dbview 
structures, and n is the number of elements in 
the array. 


Description: 


DBSTRUCTVIEW selects fields from the file re- 
ferred to by the filename parameter of this 
call. 
The list of fields in the array of 
dbview structures defines the data structure to 
be used by future ALL calls. 
Any fields within 
the file specified in the filename parameter 
may be specified in the array of dbview struc- 
tures pointed to by the fieldlist. 
The C 
language data structure defined by the user 
must have a one-to-one correspondence to the 
array of dbview structures passed to 
DBSTRUCTVIEW by the fieldlist parameter. 


After the DBSTRUCTVIEW call completes suc- 
cessfully, each dbview structure in the 
fieldlist array holds information about each 
field specified in the fieldlist array. 
This 
information includes the view starting byte, 
length, and data type for each field specified 
in the fieldlist array. 
You can use this in- 
formation to improve data independence between 
your C source code and INFORMIX database. 
The 
dbview structure is defined in the dbio.h in- 
clude file. 


Subsequent ALL calls which read records 
from the database place data from the record 
being read into a C language structure defined 
by the user. 
Depending on the data type of a 
given field, data from that field in the data- 
base is copied into the user's data structure 
in a particular way. 
Fields of type CHARACTER 
are copied into the user-defined structure with 
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a NULL terminator, so type CHARACTER fields 
must always be defined as being one byte larger 
than their field length in the database. 
Fields of type DOUBLE or INTEGER are copied 
into the user-defined structure properly 
aligned for subsequent arithmetic or C language 
manipulations. 


If DBSTRUCTVIEW is used to define a view 
for a file, the address of the user-defined 
data structure must be passed as the recbuf 
parameter to the DBFIND library callo 


If both calls to DBSTRUCTVIEW and DBSET- 
FILEVIEW are used in the same program for the 
same file, information is copied into the user 
data area in the fashion of the most recently 
called DBSTRUCTVIEW or DBSETFILEVIEW. 
In other 
words, the user has a choice between reading 
fields from the database in the fashion of a C 
language data structure using DBSTRUCTVIEW, or 
in the "fashion of a non-aligned buffer area us- 
ing DBSETFILEVIEW. 


Error Codes: 
o - call executed successfully 


6005 - a field cannot be found 


6006 - filename has not been opened 


6024 - memory allocation error, out of memory 


6051 - composite field names are not allowed in 
dbview 


-1 - internal error 
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11.0. 
DBSELFIELD 


Command Format: 


dbselfield(filename,fieldname,flag) 
char *filename; 
char *fieldname; 
int flag; 


Parameters: 


Filename is a pointer to the file name, field- 
name is a pointer to the field name that is to 
be used in keyed reading by the DBFIND routine, 
and flag indicates whether or not the fieldname 
parameter is to be used. 


Flag can be any of the following: 


ACCKEYED for access by selected indexed field. 


ACCSEQUENTIAL for access in physical order in 
data file. 


ACCPRIMARY for access by primary key -- returns 
records in chronological order if no primary 
key was explicitly specified in DBBUILD. 


Description: 


If you set the ACCKEYED or ACCPRIMARY flags, 
DBSELFIELD ignores the fieldname parameter. 
If 
a specific field is requested, the records will 
be read in an order determined by the values of 
that field. 
The field must have had an index 
built for it previously through the use of 
DBBUILD or the add index command in DBSTATUS. 
If no fields in the file have indexes, the im- 
plicit system index may be used. 


Once an index is set with the DBSELFIELD call 
for a given file it need not be reset, even 
though DBFIND may be used to read from more 
than one file over the course of a program's 
execution. 
For users of the Application 
Language library who have source code written 
before version 2.00, a synonym routine called 
DBSELATT can be used instead of DBSELFIELD. 
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Error Codes: 
o - call executed successfully 


6007 - field name cannot be found in the current 
file 


6008 - file has not been opened 


6026 - the named field must be keyed or 
chronological must be selected 


6052 - not all of the composite field is contained 
in the current view 


-1 
- internal error 
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II.E. 
DBFIND 


Command Format: 


dbfind(filename,flag,value,length,recbuf) 
char *filename; 
int flag; 
char *value; 
int *length; 
char *recbuf; 


Parameters: 


Filename is a pointer to the name of the file 
that is being accessed. The flag integer is ei- 
ther COMPARISON, 
EQUAL, GTEQ, 
GREATER, 
FIRST, 
LAST, 
CURRENT, 
NEXT or PREVIOUS. 
The CURRENT 
flag re-reads the current record. 
If the flag 
is COMPARISON, 
OR EQUAL, value must be a 
pointer to a value of the appropriate type. 


Under UNIX, you can lock the record before it 
is read into the user's data area. 
LOCK should 
be arithmetically added to the flag parameter 
(NEXT 
+ LOCK). 
The record can then be unlocked 
later by calling DBUNLOCK with the file name of 
the locked record as its argument. 


The value parameter is a pointer to the search 
value upon which the search is based. 
If the 
field being compared is of type INTEGER or DOU- 
BLE, a pointer to an integer or double must be 
passed in the value parameter. 
The length 
parameter is a pointer to an integer that will 
receive the length of the view read by DBFIND. 
The recbuf parameter is a pointer to a charac- 
ter bUffer, if DBSETFILEVIEW was used, or a 
data structure, if DBSTRUCTVIEW was used. 
If 
the field being compared is of type COMPOSITE, 
a null pointer should be passed in the value 
parameter, as more than one value cannot be 
passed. 
The value in the structure recbuf will 


then be used as the search value. 


Description: 


The DBFIND system routine allows the user to 
read records from files on a record-by-record 
basis. 
The length parameter will be used to 
return the length of the record that is read. 
This length will depend on the view last set 
for the file by the DBSETFILEVIEW or 
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DBSTRUCTVIEW routine. 
The data in the record 


will be placed in the record buffer or data 
structure pointed to by recbuf. 


Error Codes: 
o - call executed successfully 


6009 - no data in the file 


6010 
value cannot be found 


6011 - end of file 


6012 - beginning of file 


6014 - no such flag value 


6015 - filename has not been opened 


6016 - no view has been set 


6035 - no current record 


6045 - no field has been selected 


-1 
- internal error 
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II.F. 
DBUPDATE 


Command Format: 


dbupdate(filename,recbuf) 
char .*filename; 
char *recbuf; 


Parameters: 


The filename parameter points to the name of 
the file in which the record to be updated is 
located, and recbuf points to the application 
program's memory area from which the record to 
be updated will be taken. 


Description: 


This library routine allows the programmer to 
update records in the database. 
The most re- 
cent view set by DBSETFILEVIEW or DBSTRUCTVIEW 
for the file will be used. Fields not listed in 
that view will retain their original values. 


Error Codes: 
o - call executed successfully 


6020 - no current record to update 


6028 - filename has not been opened 


6029 - no view has been set 


6030 - cannot add a duplicate value - 
NODUPS 
option is in effect 


-1 - internal error 
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II.G. 
DBADD 


Command Format: 


dbadd(filename,recbuf) 
char *filename; 
char *recbuf; 


Parameters: 


The filename parameter points to the name of 
the file to which a record is to be added. 
Recbuf points to the application program's 
memory area from which the record to be added 
will be taken. 


Description: 


This library routine allows the programmer to 
add records to files in the database. 
The most 


recent view set by DBSETFILEVIEW or 
DBSTRUCTVIEW for the file referred to by 
filename will be used. 
Fields not listed in 
that view will be filled with binary zeros if 
their data type is INTEGER or DOUBLE and blanks 
if their data type is CHARACTER. 


Error Codes: 
o - call executed successfully 


6017 - cannot add a duplicate value - NODUPS option 
is in effect 


6018 - filename has not been opened 


6019 - no view has been set 


-1 - internal error 
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II.H. 
DBDELETE 


Command Format: 


dbdelete(filename) 
char *filename; 


Parameters: 


Filename indicates the file from which the 
record is to be deleted. 


Description: 


This routine will delete the record most re- 
cently read from the specified file using the 
DBFIND routine. 


Error Codes: 


o - command executed successfully 


6020 - there is no current record 


6021 - filename has not been opened 


-1 - internal error 
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11.1. 
DBLOCK 


Command Format: 


dblock(filename) 
char *filename; 


Parameters: 


Filename is a pointer to the name of the 
current file. 


Description: 


DBLOCK is available on UNIX systems only. 


This routine allows the applications programmer 
to ensure that the integrity of the database 
will not be destroyed through the problems that 
are introduced by sharing data in a concurrent 
processing environment. The problem arises when 
two processes have each read the same part of 
the database into their program data area and 
have changed that data before writing it back 
out. If both of the processes have read before 
either of them has written, then one of the up- 
dates will not be reflected in the database 
after both of the processes have written the 
data back out. Only the process that writes 
last will have actually effected the desired 
change to the database. The data that the first 
process changed would have been overwritten by 
the actions of the second process. 


Update activities on the same data must be 
serialized so that when two updates are to oc- 
cur, the second process to perform the update 
operates on a copy of the data that has already 
been updated by the first process. This implies 
that if both processes desire to perform the 
update process at nearly the same time, one is 
going to have to wait for the other, even 
though it is usually a very short time. The da- 
tabase system allows the two processes to au- 
tomatically synchronize the serialization of 
their activities through the DBLOCK and DBUN- 
LOCK calls. 


Thus, if all programmers that are writing pro- 
grams that use the library routines to update 
files surround the reading and writing with 
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locking and unlocking calls, all such updates 
will be serialized and all concurrency control 
problems will be solved. 


One final problem must be considered by the ap- 
plications programmer to assure that the lock- 
ing mechanisms in the program perform correct- 
ly. 
The database system must protect the 
operating system from a phenomenon known as 
deadlock. 
Deadlock occurs when one process has 
locked a resource and is waiting for a resource 
that is locked by another process. That other 
process is waiting for the 
res~urce that the 
first process has locked. 
Both these processes 
will wait forever. 
Furthermore, any process 
that attempts to lock either of these two 
resources will join the group of never-ending 
processes. 


Error Codes: 
o - command executed successfully 


6022 - lock was denied 


6023 - filename has not been opened 


-1 - internal error 
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II. J • 
DBUNLOCK 


Command Format: 


dbunlock(filename) 
char *filename; 


Parameters: 


Filename is a pointer to the name of the 
current file. 


Description: 


DBUNLOCK is available on UNIX systems only. 


Any locks that are placed with the DBLOCK or 
DBFIND routines can be removed by the applica- 
tions programmer after the update to the file 
through the use of this routine. 


Error Codes: 


o - command executed successfully 


6023 - filename has not been opened 


-1 
- internal error 
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II. K. 
DBVERSION 


Command Format: 


dbversion( ) 


Parameters: 


None. 


Description: 


DBVERSION allows the programmer to print a 
header containing the INFORMIX version number 
and the software serial number. 
The lines 


INFORMIX version 3.20 
Copyright (e) 1981, 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-000001 


will be sent to standard output. 


Error Codes: 


None. 
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II.L. 
DBFILE 


dbfile(filename, numflds, recsize, perms) 


char *filename; 
short *numflds; 
short *recsize; 
short *perms; 


Description: 


DBFILE returns the contents of the data dic- 
tionary. 
It returns information about any file 
in an INFORMIX database including a count of 
the fields in the file, the record size of 
records in the file, and, on UNIX systems, a 
bitmap of the permissions granted to the 
current user. 


Parameters: 


filename -- a pointer to a null-terminated 
string provided by the user. 
The string holds 
the name of the file whose information is to be 
retrieved by DBFILE. 


numflds -- a pointer to a short integer. 
The 
count of the fields within the file as known by 
the data dictionary will be placed in this 
short by DBFILE when it completes successfully. 


recsize -- a pointer to a short integer. 
The 
record size as known by the data dictionary 
will be placed in this short by DBFILE when it 
completes successfully. 


perms 
~~ a pointer to a short integer. 
This 
parameter is only available on UNIX systems. 
A 
bit map of the permissions granted to the 
current user 10 (uid) will be placed here when 
DBFILE completes successfully. 
The follOWing 
macro definitions can be used to determine 
which access permissions are granted. 
These 
definitions can be found in dbio.b. 


PERM READ 
PERM-UPDATE 
PERM-INSERT 
PERM-DELETE 
PERM-CONTROL 
PERM-ALL 
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(The PERM INSERT permission performs the same 
function as "add" permission in the schema.) To 
test whether any particular access is granted, 
take the value in the perms parameter after a 
call to DBFILE, and perform a bitwise AND 
operation on it, and see if the result is true. 
Refer to the following example. 


short numflds, recsize, perms 


dbfile( "agents II , 
Benumflds, Berecsize, Beperms); 


if (perm 
Be PERM READ) 
printf( "You-have READ access for this file. \n"); 
if (perm 
Be PERM UPDATE) 
printf("You-have UPDATE access for this file. \n"); 
if «perm 
Be PERM ALL) == PERM ALL) 
printf("You nave all types of access to this file.\n"); 


Error Codes: 


6000 - database not open yet 


6001 - file not in database 
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II.M. 
DBNFILE 


dbnfile(filenum, filename, numflds, recsize, perms) 


short filenum; 
char *filename; 
short *numflds, *recsize, *perms; 


Description: 


DBNFILE returns the contents of the data dic- 
tionary. 
It returns information about any file 
in an INFORMIX database including the null- 
terminated name of the file, a count of the 
fields in the file, the record size of records 
in the file, and, on UNIX systems, 
a bit map 
of the permissions granted to the current user. 


Parameters: 


filenum -- a short integer value that specifies 
the nth file in the database. 
The user passes 
o through n for information about the first 
through the nth 
+ 1 file respectively. 
To get 
information about all the files in the data- 
base, call OBNFILE in a loop passing it incre- 
menting values for filenum until OBNFILE re- 
turns a condition code not equal to zero. 


filename -- a pointer to a character array. 
OBNFILE returns the null-terminated name of the 
nth file in this array. 


numflds -- a pointer to a short integer. 
The 
count of the fields within the file as known by 
the data dictionary will be placed in this 
short by OBNFILE when it completes successful- 
ly. 


recsize -- a pointer to a short integer. 
The 
record size as known by the data dictionary 
will be placed in this short by OBNFILE when it 
completes successfully. 


perms -- a pointer to a shprt integer•. This 
parameter is only available on UNIX systems. 
A 
bit map of the permissions granted to the 
current user 10 (uid) will be placed here when 
OBNFILE completes successfully. 
The follOWing 
macro definitions can be used to determine 
which access permissions are granted. 
These 
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definitions can be found in dbio.h. 


PERM READ 
PERM-UPDATE 
PERM-INSERT 
PERM-DELETE 
PERrrCONTROL 
PERM-ALL 


Refer to DBFILE for an example of the use of 
perms. 


Error Codes: 


6000 - database not open 


6001 - file not in database 
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II.N. 
DBFIELD 


dbfield(filename, fldname, type, len, perms) 


char *filename, *fldname; 
short *type", *len, *perms; 


Description: 


DBFIELD returns information about a particular 
field within a file of an INFORMIX database, 
including the data type, length, and, on UNIX 
systems, permissions granted for the field. 


Parameters: 


filename -- a pointer to a null-terminated 
string provided by the user. 
The string holds 
the name of the file that contains the field 
fldname. 


fldname -- a pointer to a null-terminated 
string provided by the user. 
The string is the 
name of the field for which information will be 
returned by this call to DBFIELD. 


type -- a pointer to a short integer that will 
be returned by DBFIELD. 
After a successful 
call to DBFIELD, this short will contain a 
value that describes the data type of the field 
fldname. 
The possible values are shown below. 


CHARTYPE 
INTTYPE 
LONGTYPE 
DOUBLETYPE 
FLOATTYPE 
SERIALTYPE 
DATETYPE 
EDATETYPE 
YDATETYPE 
DATESIZE 
MONEYTYPE 
COMPOSTYPE 


len -- a pointer to a short integer that will 
be returned by DBFIELD. 
After a successful 
call to DBFIELD, this short will contain the 
length of the field In bytes. 
If the field has 
type COMPOSTYPE, the len parameter will hold 
the number of parts that the composite field 
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has (see DBNCOMPOSITE). 


perms -- a pointer to a short integer that will 
be returned by DBFIELD. 
This parameter is only 
available on UNIX systems. 
After a successful 
call to DBFIELD, this short will contain a bit- 
map of the permissions granted the current 
user. 
For an explanation of the use of the 
permissions bitmap see the section on permis- 
sions in the discussion of DBFILE. 


The bitmap PERM ALL will not correctly indicate 
all permissions-on fields. 
To get permission 
of fields, use PERM READ, 
PERM UPDATE, 
PERM INSERT, and PERM DELETE in combination. 
For example: 
- 
if (perm & PERM READ 
&& perm & PERM UPDATE 
&& perm & PERM-INSERT 
&& perm & PERM-DELETE) 
printf("User has all permissions on field.\n) 


Error Codes: 


6000 - database not open 


6001 - file not found in database 


6007 - field not found in file 
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11.0. 
DBNFIELD 


dbnfield(fldnum, filename, fldname, type, len, perms) 


short fldnum; 
char *filename, *fldname; 
short *type, *len, *perms; 


Description: 


DBNFIELD returns information about a particular 
field within a file of an INFORMIX database. 
This information includes the name, data type, 
length, and, on UNIX systems, 
permissions 
granted for the field. 


DBNFIELD is primarily useful when the names of 
fields within a file are not known. 
DBNFIELD 
can then be used within a loop to extract the 
field name as well as field information for 
each field. 


Parameters: 


fldnum -- a short integer value passed to 
dbnfield by the user. 
The acceptable values 
for fldnum are from 0 to n. 
A value of zero 
corresponds to the first field in the file 
named in filename, a value of 1 corresponds to 
the second field, and so on. 


filename -- a pointer to a null-terminated 
string provided by the user. 
The string is the 
name of the file that contains the field 
fldname. 


fldname -- a pointer to a character array. 
DBNFIELD returns the null-terminated name of 
the field associated with fldnum in this array. 


type ---a pointer to a short integer that will 
be returned by DBNFIELD. 
After a successful 
call to DBNFIELD, this short integer will con- 
tain a value that describes the data type of 
the field fldname. 
The possible values are 
shown below. 


CHARTYPE 
INTTYPE 
LONGTYPE 
DOUBLETYPE 
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FLOATTYPE 
SERIALTYPE 
DATETYPE 
EDATETYPE 
YDATETYPE 
DATESIZE 
MONEYTYPE 
COMPOSTYPE 


len -- a pointer to a short integer that will 
be returned by DBNFIELD. 
After a successful 
call to DBNFIELD, this short will contain the 
length of the field in bytes. 
If the field has 
type COMPOSTYPE, the len parameter will hold 
the number of parts that the composite field 
has (see DBNCOMPOSITE). 


perms -- a pointer to a short integer that will 
be returned by DBNFIELD. 
This parameter is 
only available on UNIX systems. 
After a suc- 
cessful call to DBNFIELD, this short will con- 
tain a bitmap of the permissions granted the 
current user. 
For an explanation of the use of 
the permissions bitmap, see the section on per- 
missions 
~n the discussion of DBFILE. 


Error Codes: 


6000 - database not open 


6001 - file not in database 


6041 


INFORMIX 


fldnum parameter is greater than the 
number of fields in the file 
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II.P. 
DBNCOMPOSITE 


dbncomposite(ncomp, filename, compname, partname, 
ptype, plen, pperms) 


short ncomp; 
char *filename, 
*compname, *partname; 
short ·ptype, *plen, *pperms; 


Description: 


DBNCOMPOSITE returns database dictionary infor- 
mation about composite fields, 
including the 
name of the composite part of the multiple-part 
composite field, as well as the type, length, 
and, on UNIX systems, permissions granted on 
that part. 
DBNCOMPOSITE is used when DBFIELD 
or DBNFIELD re turns 
CO~1POSTYPE as the type 
parameter. 


P3rameter-s: 


ncamp -- a Short integer value passed to 
nBNC,.)MPOSI'fE by the user. 
A value of 0 


corr-espon.l~ to the first perot of the composite 
field: 
3 v,lue of n corresponds to the nth 
+ 1 


p:1rt )f the 
~omposite field. 
If a composite 


fieLi 
h::lS three p<:lrts, then l"lBNC0MPOSITE must 
be 
call~1 three times to retr-ieve information 
about 
e3~h of the c0mr0site field's parts. 


filen,me -- a pointer- to a null-terminated 


strin~ pr0vided by the user. 
The string is the 


name of tne file that contains the field comr- 
name. 


c.ompn:1me -- a 
;loi~1ter- to 
.3 null-termin"lted 


;:;t:"in~ 
~'('ovijed by the user. 
The strini1: is the 


n:1me of thp. fio'!ld 
for- which information will be 
e)(tr- ..~cte·l 
by this c:111 to Di3tJCOMPOSIl'E. 


psr-tname -- a ?ointer to a null-terminated 


strin~ that will be returned by DBNCOMPOSITE. 
After- succegs[ul completion of DBNCOMPOSITE, 
par-tn:1me will contain a null-terminated string 
that is the fie ld n:1me of the composi te p,,:-t. 


ptype -- a pointer to a short 
inte~er that will 
be returned 
by DBNCOMPOSITE. 
After- a success- 
ful call to DBNCOMPOSITE, this short integer 
will contain 
<:I value that descr-ibes the data 
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type of the field partname. 
The possible 
values are shown below. 


CHARTYPE 
INTTYPE 
LONGTYPE 
DOUBLETYPE 
FLOATTYPE 
SERIALTYPE 
DATETYPE 
EDATETYPE 
YDATETYPE 
DATESIZE 
MONEYTYPE 


plen -- a pointer to a short integer that will 
be filled in by DBNCOMPOSITE. 
After a success- 
ful call to DBNCOMPOSITE. this short will con- 
tain the length of the field in bytes. 


pperms -- a pointer to a short integer that 
will be filled in by DBNCOMPOSITE. 
This param- 
eter is only available on UNIX systems. 
After 
a successful call to DBNCOMPOSITE. 
th~s short 
will contain a bitmap of the permissions grant- 
ed the current user. 
For an explanation of the 
use of the permissions bitmap. see the section 
on permissions in the discussion of DBFILE. 


Error Codes: 


6000 - database not open 


6006 - file not yet open 


6007 - field not found 


6043 - field is not a composite field type 


6044 - ncomp parameter is greater than the count 
of composite parts of the field 
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II. Q. 
DBALIAS 


dbalias(newname, oldname) 


char *newname, *oldname; 


Description: 


DBALIAS lets a user open an INFORMIX database 
file more than once. 
It does this by allowing 
the user to reference a file by more than one 
name. 
A DBALIAS call may be made any time 
after the database is opened. 
An aliased name 
responds to Application Language Library calls 
exactly as if it was a separate file from the 
original. 
This allows users to access a file 
in many different ways simultaneously. 


Parameters: 


newname -- a pointer to a user-supplied, null- 
terminated string that contains the new name 
for the file. 
In subsequent calls to Applica- 
tion Language Library sUbroutines, the user can 
use this new name to reference the original 
file. 


oldname -- a pointer to a user-supplied, null- 
terminated string that contains the name of the 
file as it is known in the database dictionary. 


Error Codes: 


6000 - database not open yet 


6024 - out of memory 


6036 - the newname parameter already exists 


6037 - the newname parameter has already been 
used previously as an alias 


6038 - an alias may not be an alias of an 
existing alias 
as a field or filename in the database 


6040 - the oldname parameter was not found as 
a file name in the database 
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H.R. 
DBINDEX 


dbindex(filename, fldname, idxtype) 


char *filename, *fldname; 
short *idxtype; 


Description: 


DBINDEX lets the user determine whether a 
specified field has an index already built for 
it in an INFORMIX database. 
It also tells the 
user whether that index allows or disallows du- 
plicate key values. 


Parameters: 


filename -- a pointer to a user-supplied, 
null-terminated string that is the name of the 
file in which tldnaae can be found. 


fldname -- a pointer to a user-supplied, null- 
terminated string that is the name of the field 
this call refers to. 


idxtype -- a pointer to a short integer that 
will be returned by DBINDEX. 
After successful 
completion of this call, idxtype will contain 
one of three values NOINDEX, NODUPS, or DUPS. 
NOINDEX indicates that there is no index for 
the field fldname. 
NODUPS indicates that there 
is an index for the field fldname, but that 
that index does not allow duplicate key values 
to be placed in the field. 
DUPS indicates that 
there is an index for the field fldname and. 
that it does allow duplicate key values. 


Error Codes: 


6007 - field not found in file 


60t5 - file not yet open 
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II.S. 
DBADDINDEX 


dbaddindex(filename, fldname, dupsorno) 


char *filename, *fldname; 
short dupsorno; 


Description: 


The DBADDINDEX function allows users to add an 
index for a specified field within an INFORMIX 
database. 
To add an index, the user must have 
CONTROL access to the file and must have opened 
the file using DBSELECT with the 
FILEOPEN+EXCLUSlVE parameter. 


Parameters: 


filename -- a pointer to a user-supplied, 
null-terminated string that is the name of the 
file in which tldna-e can be found. 


fldname -- a pointer to a user-supplied, null- 
terminated string that contains the field name 
for which the index is to be added. 


dupsorno -- ·a user-supplied, short integer 
value that is zero when duplicate key values 
are not to be allowed, and non-zero when dupli- 
cate key values are allowed. 


Error Codes: 


6007 - field does not exist in file 


6015 - file not yet open 


6046 - file not opened exclusively 


6047 - index already exists 


6048 - a duplicate key value was found while 
adding an index for which NODUPS 
was specified 


6049 - the current user does not have control 
access that is needed to add an index 


6050 - bad key description: internal error 
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II.T. 
DBDELINDEX 


dbdelindex(filename, fldname) 


char *filename, *fldnamej 


Description: 


The DBDELINDEX function deletes an index for a 
specified field within an INFORMIX database. 
To delete an index, the user must have CONTROL 
access to the file and must have opened the 
file using DBSELECT with the FILEOPEN+EXCLUSIVE 
parameter. 


Parameters: 


filename -- a pointer to a user-supplied, 
null-terminated string that is the name of the 
file in which fldname can be found. 


fldname -- a pointer to a user-supplied, null- 
terminated string that contains the field name 
for which the index is to be deleted. 


Error Codes: 


6007 
field does not exist in file 


6015 - file not yet open 


6046 
file not open exclusively 


6049 - the current user does not have the 
control access required for 
deletion of an index 


6050 - bad key description: internal error 
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II.U. 
DBPRUSING 


dbprusing(tohere, format, value} 


char *tohere, *format; 
double value; 


Description: 


DBPRUSING lets the user format double floating 
point values in the fashion allowed by ACE, 
INFORMIX's report writer. 
This includes the 
ability to format values with leading dollar 
signs, leading minus signs, encompassing 
parentheses, and left-justification. 
For more 
discussion of the possible formats available, 
see the ACE chapter for the PRINT USING state- 
ment. 


Parameters: 


tohere 
user-supplied pointer to the memory 
location where the user wants DBPRUSING to put 
the final formatted result. 


format -- pointer to a user-supplied, null- 
terminated string which contains the printing 
format. 


value -- the user-supplied, double-precision 
floating point number that is to be formatted. 


Return Codes 


none 
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III. 
ALL-II Interface 


III.A. 
Error Trapping 


Each of the library routines returns a condi- 
tion code. This code should always be compared to 
zero. 
If it is other than zero, its value is an in- 
dicator of an 
exceptional condition. 
The explana- 
tion of each call in this chapter includes a discus- 
sion of the possible condition codes. 
In addition 
to the condition codes listed for each call, a -1 
may also be returned. 
This would indicate that an 
internal or system error occurred during the execu- 
tion of the call. 
It is the responsibility of the 
programmer to handle these exceptional conditions in 
a fashion that is reasonable for the particular pro- 
gram being written. 


III.B 
Argument Formats 


Some of the routines 
have character strings 
for arguments. These arguments may be replaced by 
arrays of type CHAR in C. 
These variables are ex- 
pected to contain or point to null-terminated 
strings. 


Some of the routines have record buffers for 
arguments. These buffers should be addresses of 
buffers that are large enough to hold the data that 
is being returned. 
The length of the data that ac- 
tually was returned should be checked to ensure that 
the program is operating as expected. 


III.C. 
Interrupt Signals 
\ 


In order to ensure the internal integrity of 
certain database files, the DBADD, 
DBDELETE, and 
DBFIND calls contain critical sections which must be 
allowed to complete without interruption. 
The 
operating system call signal will be used to ignore 
the interrupt signal during these critical sections. 
The interrupt signal will be reinstated with the de- 
fault action when the critical section has complet- 
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ed. 
This is the default method of handling inter- 
rupts. 


You can override the default method and gain 


more control over how signals are handled; refer to 
the SIGINIT and SIGPROC ALL-II calls described in 
Section IrI.F. 


III.D. 
Including the ALL Routines 


The Applications 
Lan~uage Library (libdb.a) 
should be located in the lusr/lib directory. 
ALL 
routines that are called from the user's program 
viII be included when the -ldb argument is included 
in the user's link line. 
For example, to compile 
and link an ALL program called ayprog, give the com- 
mands 


cc myprog.c -ldb -0 myprog 


The All programmers' package comprises 
llbdb.llb and dbl0.h. 
To use these C language pro- 


gramming tools, you must have the Lattice C compiler 
version 2.0. 
Compile your C programs with Lattice 
2.0 using the P-model option, and link them with the 
Lattice 6 P-model library and the RDS ALL library. 


For example, to compile and link an ALL program 


called myprog, give the commands 


>lc1 myprog -mp 
>lc2 myprog 
>link cp+myprog,myprog"libdb+lcp 


III.E. 
Curses and Terac"p Support 


Under UNIX, the Application Language Library sup- 
ports the follovins functions. 
[Subvindows (subwin) 
are not supported.j 
Documentation for the Curses 


routines is in Section 3 of the UNIX Programmer's 
Manual. 
Documentation for the Termcap routines is 
in Section 5 of the UNIX Programmer's Manual. 
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Curses: 
sprintw 


delwin 
endwin 
initscr 
newwin 
printw 
touchwin 
waddch 
waddstr 
wclear 
wclrtobot 
wclrtoeol 
wdeleteln 
werase 
winsertln 
wmove 
wprintw 
wrefresh 
wstandend 
wstandout 


Termcap 
tgetent 
tgetflag 
tgetnum 
tgetstr 
tgoto 
tputs 


III.F. 
RDS Library Extension 


The routines listed on the following pages 
comprise the RDS library extension. 


· . 
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RBYTECMP 


rbytecmp(byte1, byte2, length) 


char *byte1; 
char *byte2; 
int length; 


Description: 


The RBYTECMP routine compares two groups of 
contiguous bytes for a given length, returning 
the results of the comparison as the value of 
the function. 
If the group of bytes pointed to 
by byte1 would appear later in the dictionary 
than the group of bytes pointed to by byte2, 
the result will be greater than zero. 
If the 
group pointed to by byte1 is less than the 
group of bytes pointed to by byte2, the result 
will be less than zero. 
If the two groups are 
identical, the result will be zero. 


Parameters: 


byte1 -- A pointer to the starting location of 
the first group of contiguous bytes. 


byte2 -- A pointer to the starting location of 
the second group of contiguous bytes. 


length -- The number of bytes over which the 
comparison will occur. 
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RBYTECPY 


rbytecpy(from, to, length) 


char *from; 
char *to; 
int length; 


Description: 


The RBYTECPY routine copies bytes from one lo- 
cation to another for a length specified by the 
length parameter. 


Parameters: 


from -- The pointer to the starting byte that 
the bytes will be copied from. 


to -- The pointer to the starting byte that the 
bytes will be copied to. 


length -- The number of bytes to be copied. 
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RBYTEFILL 


rbytefill(to, length, ch) 


char *to; 
int length; 
char ch; 


Description: 


The RBYTEFILL routine fills a specified area 
vith one character. 


Parameters: 


to -- The starting byte of the memory area to 
be filled. 


length -- Hov many times the character viII be 
repeated vithin the area. 


ch -- The character that viII fill the area. 
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RCHARFILL 


rcharfill(start, stop, from) 


char *start; 
char *stop; 
char *from; 


Description: 


The RCHARFILL routine replicates a character 
pointed to by the from parameter starting at 
the character pointed to by start and ending 
with the character position pointed to by stop. 
The replication occurs only over those bytes 
which are non-printable ASCII characters. 
This 
routine is useful for blank-filling fields 
which may have non-printable characters already 
imbedded in them, but where the data is to 
remain intact. 


Parameters: 


start -- The first byte to which the character 
pointed to by the from parameter may be copied. 


stop -- The last byte to which the character 
pointed to by the from parameter may be copied. 


from -- A pointer to the character that will be 
copied to the locations specified by the start 
and stop parameters. 
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RTODAY 


rtoday(pdate) 


long pdate; 


Description 


The RTODAY routine converts the system's date 
into an INFORMIX internal data type date and 
places it into a long. 
INFORMIX internal dates 
are always in the form of a long with a value 
of the number of days since January 1, 1900. 


Parameters: 


pdate 
A pointer to a long where the date is 
to be stored. 
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RDATESTR 


rdatestr(julian, string, type) 


long julian; 
char *string; 
int type; 


Description: 


The RDATESTR routine looks at an internal IN- 
FORMIX data type DATE, EDATE, or YDATE field 
and creates a null-terminated string in either 
DATE, EDATE, or YDATE format. 
DATE format is 
mm/dd/yy; 
EDATE format is dd/mm/yy; and YDATE 
format is yy/mm/dd. 


Parameters: 


julian 
A long integer whose value is the 
number of days since January 1, 1900. 


string 
A pointer to an area in memory where 
the formatted result will be put. 


type -- An integer value that specifies the 
result format. 
Use one of three macro defini- 
tions DATETYPE, 
EDATETYPE, or YDATETYPE. 
These 
macro definitions can be found in dbio.h. 
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RSTRDATE 


rstrdate(string, pjulian, type) 


char *string; 
long *pjulian; 
int type; 


Description: 


The RSTRDATE routine looks at a string in the 
format of mm/dd/yy, dd/mm/yy, or yy/mm/dd and 
initializes a long, pointed to by the parameter 
pjulian, to the number of days between it and 
January 1, 1900. 
The long will be an internal 
INFORMIX data type date and can be assigned or 
compared to any INFORMIX field of type DATE, 
EDATE, or YDATE• 


• <• 
.. . 
Parameters: 


string 
A pointer to a null-terminated string 
in either mm/dd/yy, dd/mm/yy, or yy/mm/dd for- 
mat. 


pjulian -- A pointer to a long that will store 
the result as the number of days between Janu- 
ary 1, 1900 and the formatted date pointed to 
by the parameter string. 


type -- An integer value of either DATETYPE, 
EDATETYPE, or YDATETYPE. 
The value of this 
parameter must correspond to the format of the 
string (i.e., DATETYPE for mm/dd/yy, EDATETYPE 
for dd/mm/yy, and YDATETYPE for yy/mm/dd). 
These macro definitions can be found in dbio.b. 
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RJULMDY 


rjulmdy(julian, mdy, type) 


long julian; 
short mdy[3]; 
int type; 


Description: 


The RJULMDY routine looks at an INFORMIX data 
type date, edate, or ydate and initializes an 
array of three shorts to the month, day, and 
year values for that date. 
The order of the 
month, day, and year values stored in the array 
is specified by DATETYPE, EDATETYPE, or 
YDATETYPE in the type parameter. 


Parameters: 


julian -- A long integer that has the value of 
the number of days since January 1, 1900. 


mdy[] -- A pointer to an array of shorts where 
the result is returned. 


type -- An integer value that is either 
DATETYPE, EDATETYPE, or YDATETYPE. 
This value 
must correspond to the order in which the mdy 
array is to be filled: 
DATETYPE for month-day- 
year; 
EDATETYPE for day-Month-year; or 
YDATETYPE for year-Month-day order. 
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RMDYJUL 


rmdyjul(mdy, pjulian, type) 


short mdy[3]; 
long *pjulian; 
int type; 


Description: 


The RMDYJUL routine looks at an array of shorts 
initialized to either month-day-year, day- 
month-year, or year-month-day order (specified 
by the type parameter). 
It then initializes a 
long, pointed to by pjulian, to the number of 
days between the date found in mdy and January 
1, 1900. 


Parameters: 


mdy -- A pointer to an array of shorts. 
One 
short per month, day, and year respectively. 
The order of these array elements is specified 
to RMDYJUL by passing either DATETYPE, 
EDATETYPE, or YDATETYPE as the value for the 
type parameter. 


pjulian -- A pointer to a long where the result 
is to be .returned. 


type -- An integer value either DATETYPE, 
EDATETYPE, or YDATETYPE indicating the order of 
the array elements of the mdy parameter. 
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RDOWNSHIFT 


rdownshift(s) 


char *s; 


Description: 


The RDOWNSHIFT routine takes all of the charac- 
ters within a null-terminated string and 
changes them to lowercase. 


Parameters: 


s -- A pointer to a null-terminated string. 
After the call to RDOWNSHIFT, this string will 
have all letters put in lowercase. 
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RUPSHIFT 


rupshift(s) 


char *s; 


Description: 


The UPSHIFT routine takes all of the characters 
within a null- terminated string and changes 
them to uppercase. 


Parameters: 


s -- A pointer to a null-terminated string. 
After the call to UPSHIFT, this string will 
have all letters put in uppercase. 
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RLADJUST 


rladjust(left, stop) 


char *leftj 
char *stop; 


Description: 


The RLADJUST routine left-adjusts printable 
characters within an area. 
Left-adjusted char- 
acters are replaced by blanks in their original 
positions. 


Parameters: 


left -- A pointer to the location in memory 
where the left-adjustment is to take place. 


stop -- A pointer to the location in memory 
where the left-adjustment is to end. 
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RRADJUST 


rradjust(left, right, filler) 


char *left, *right; 
char filler; 


Description: 


The RRADJUST routine right-adjusts printable 
characters within a specified field of memory. 
Moved characters are replaced by a specifiable 
fill character. 


Parameters: 


left -- A pointer to the leftmost, or low- 
order, byte of the field to be right-adjusted. 


right -- A pointer to the rightmost, or high- 
order, byte of the field to be right-adjusted. 


filler -- A character that writes over the old 
positions of right-adjusted characters. 
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RSTRCAT 


rstrcat(s1, 52) 


char *s1, *s2; 


Description: 


The RSTRCAT function concatenates one null- 
terminated string to the end of another. 


Parameters: 


s1 -- A pointer to the start of the first 
null-terminated string. 


s2 -- A pointer to the start of the second 
null-terminated string. 
This is the string 
that will be placed at the end of the first 
string. 
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RSTRCMP 


rstrcmp(s1, s2) 


char *s1, *s2; 


Description: 


The RSTRCMP routine compares two null- 
terminated strings according to dictionary 
sorting techniques. 
It returns a value that is 
the difference between those strings. 
The re- 
turn value is zero when the two strings are 
identical, less than zero when the first string 
is less than the second, and greater than zero 
when the first ·string is greater than the 
second. 


Parameters: 


s1 -- A pointer to the first null-terminated 
string. 


s2 -- A pointer to the second null-terminated 
string. 
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RSTRCPY 


rstrcpy(from, to) 


char *from, *to;; 


Description: 


The RSTRCPY routine copies a null-terminated 
string from one location in memory to another 
location. 


Parameters: 


from -- A pointer to the null-terminated string 
to be copied. 


'" 
to -- A pointer to a location in memory where 
the string is to be copied. 
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RSTRLEN 


rstrlen(string) 


char *string; 


Description: 


The RSTRLEN routine returns the length. in 
bytes, of a specified null-terminated string. 


Parameters: 
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RSTOI 


rstoi(string, ivaI) 


char *string; 
int ivaI 


Description: 


The RSTOI routine looks at a null-terminated 
string and initializes a specified int to a 
value which corresponds to the string. 


Parameters: 


string 
string. 


ivaI -- A pointer to an int where the result of 
the function will be held. 


Return: 


This function returns a non-zero value if there 
is an error, a zero if it is successful. 
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RSTOL 


rstol(string, long_int) 


char *string; 
long *long_int; 


Description: 


The RSTOL routine looks at a null-terminated 
string and initializes a. specified long integer 
to a value which corresponds to the string. 


Parameters: 


string 
string. 


long int -- A pointer to a long where the 
result of the function will be held. 


Return: 


This function returns a non-zero value it there 
is an error, a zero if it is successful. 
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RSTOD 


rstod(string, double_val) 


char *string; 
double *double_val; 


Description: 


The RSTOD routine looks at a null-terminated 
string and initializes a specified double to a 
value which corresponds to the string. 


Parameters: 


string -- A pointer to a null-terminated 
string. 


double val -- A pointer to a double where the 
result-of the function will be held. 


Return: 


This function returns a non-zero value if there 
is an error, a zero if it is successful. 
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SIGINIT 


siginit() 


Description: 


SIGINIT is available on UNIX systems only. 


The SIGINIT call, along with its companion rou- 
tines SIGPROC and (user-supplied) SIGCLEANUP, 
can be used to catch signals. 
If these rou- 
tines are not used, signals will be ignored 
during critical sections of code such as ad- 
ding, deleting, and updating database files. 
Signals can be generated either by the user 
pressing the DEL or RUBOUT key, or. by the 
operating system (e.g., hangup, when a dial-in 
user hangs up the modem without first eXiting 
from the program). 
Some other types of signals 
are quit and terminate. 
A quit signal is sent 
to a process when the user presses CONTROL-\. 
A terminate signal is sent to a process when 
another process kill.s it. 
(Read more about 
signals in "signal(2)," and "setjmp(3)" of your 
UNIX manual.) 


When a signal is sent to a process, a default 
action takes place. 
In some cases this default 
action is appropriate; sometimes it is not. 
How a program reacts to signals can be con- 
trolled within the program. 
The Application 
Language Library signal routines SIGINIT and 
SIGPROC offer a simple way to catch and react 
to signals. 


SIGINIT may be called at the beginning of a 
program to set what routines will be called 
when certain signals are sent to the process. 
The following table describes what routines 
SIGINIT will force to be called when the given 
signals are sent to the process. 
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SIGINT (interrupt) 
SIGHUP (hangup) 
SIGQUIT (quit) 
SIGTERM (terminate) 


Routine Called 


sig intO 
sig-hup() 
sig-quit() 
sig:::;term() 
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The sig int, sig hup, sig quit, and sig term 
routines assign a global Int, sigflag, a value 
of SIGINT, SIGHUP, SIGQUIT, or SIGTERM respec- 
tively. 
The programmer has the option at any 
time within the code to look at sigflag to see 
if any signals have been caught and then react 
accordingly. 


For instance, once SIGINIThas been called, the 
programmer need only check the value of sigflag 
to see whether any of the above signals have 
been sent to the process. 
If they have been 
sent, the programmer can then gracefully react 
to them rather then taking the system default 
action. 


INFORMIX 


ALL-II C Language Interface 


SIGPROC 


sigproc() 


Description: 


The SIGPROC routine takes two actions. 
First, 
if the global sigflag has the value of SIGINT 
(an interrupt has been received), SIGPROC sets 
sigflag to zero and calls the UNIX system call 
longjmp(3). 
The calling of longjmp(3) will 
cause the restoration of the environment to its 
state when setjmp(3) was most recently called, 
producing a non-local goto. 
Note that the glo- 
bal jmp buf that called env must be used when 
calling-the UNIX system call setjmp(3). 


Second, if the global sigflag is not SIGINT 
(some signal other than SIGINT has been re- 
ceived), SIGPROC calls a routine called SIG- 
CLEANUP. 
SIGCLEANUP does not exist in the Ap- 
plications Language Library and must be created 
by the user. 
The manner in which signals other 
than SIGINT are reacted to is determined by the 
user-written SIGCLEANUP routine, not by an Ap- 
plication Language Library routine. 
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IV. 
ALL-II Example Programs 


The following examples are programs that use 
the Application Language Library. 
They demonstrate 
most of the ALL commands, including the UNIX DBLOCK 
and DBUNLOCK calls and a possible scenario for 
avoiding concurrency problems during the update pro- 
cess. 


The first program will find all the records in 
the orders file that have the value "Files" for the 
item field. 
It will double the value in the 
quantity field for these records and write the up- 
dated records back to the file. 


The second program uses a composite key 
(cust id) to find a record in the customer file. 
The component fields of cust id are cust lna.e, 
cust_fRame and cust_num. 
- 
- 
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Example 1 


Ninclude "dbio.h" 
#define ENDOFGROUP 
Ndefine SUCCESS 0 


/* Initialize the dbview structure 
containi~the fields 
* from the permanent file orders which will make up the 
* view of the file for this program. 
*/ 
struct dbview fieldlist[] 
II"oname"}, 
I"item"}, 
I"quantity"} 
}; 


main() 
{int cc,i,j,length,quantity,comparison,counter,dummy; 
struct 
{ 
char oname[16]; /* 15 
+ 1 for 
NULL terminator 
*/ 
char item[16]; /* 15 
+ 1 for NULL terminator */ 
int 
quantity; 
} rec; 


/* Open the stores database. */ 


cc = dbselect(DBOPEN, "stores"); 
printf("cc returned from DBOPEN is 
~d.\n", cc); 


/* Select the orders file. */ 


cc = dbselect(FILEOPEN, "orders"); 
printf("cc returned from FILEOPEN is 
~d.\n", cc); 


/* Set the view for the file. */ 


cc = dbstructview("orders", fieldrist, 3); 
printf("cc returned from set struct view is 
~d.\n", cc); 


/* 
Select the index. */ 


cc = dbselfield("orders", "item", dummy); 
printf("cc returned from sel field is 
~d.\n", cc); 
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/* 
Lock the orders file. */ 


cc • dblock("orders"); 
if (cc 
!= SUCCESS) 
{ 
)rintf("dbIOCk error 


/* Find the first record having the value "File" for the */ 
/* field item. */ 


cc = dbfind("orders", 
COMPARISON, "File", &length, &rec); 
printf("cc returned from DBFIND is 
~d.\n", cc); 


/* Update the quantity. */ 


while (cc == SUCCESS) 
{ 
printf("oname = ~s, item • 
~s, quantity = ~d\n", 
rec.oname, rec.item, rec.quantity); 
rec.quantity *= 2; 
printf("after multiplication, quantity is 
~d.\n", rec.quantity); 


cc • dbupdate("orders", &rec); 
printf("cc returned from dbupdate is 
~d.\n", ce); 


/* Unlock the file to allow any pending locks to be */ 
/* processed. */ 


cc = dbunlock("orders"); 
if (cc 
!= SUCCESS) 
{ 
)rintf("dbUnIOck error - error number 
~d.\n", cc); 


/* Lock the file. */ 


cc • dblock("orders"); 
if (cc 
!= SUCCESS) 
{ 
rrintf("dblOCk error 


/* Read the NEXT record and determine if it is */ 
/* still in the file group. */ 


cc • dbfind("orders", 
NEXT, "File", &length, &rec); 
printf("cc returned from next is 
~d.\n", cc); 
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/* Comparison will be zero if first 4 bytes of strings */ 
/* compare equally. */ 


comparison = strncmp(rec.item. "File". 4); 
if (comparison 
!= 0) 
{ 
cc = ENDOFGROUP; 
I 


/* Unlock the orders file for the final time. */ 


cc • dbunlock("orders"); 
if (cc 
!= SUCCESS) 
{ 
)rintf("dbunlOCk error 


./* Close the orders file. 


- error number 
~d.\n". cc); 


*/ 


cc • dbselect(FILECLOSE. "orders"); 
printf("cc returned from FILECLOSE is 
~d.\n". ccl; 


/* 
Close the stores database. 
*/ 


cc • dbselect(DBCLOSE. "stores"); 
rintf("CC returned from DBCLOSE is 
~d.\n". cc); 
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v. 
Appendix - 
Error Messages 


error 0: 


Call executed successfully. 


This is the normal return code for all of the Appli- 
cation Language Library routines. 
It indicates that 
the routine executed successfully. 


error 6000: 


Database not yet opened. 
Tried to perform an opera- 
tion on an unopened file or database. 


The DBSELECT call is used to open and close data- 
bases and files. 
The program should be written to 
keep track of which files it has opened, and should 
not attempt to perform any operation on a file or 
database that has not been opened. 
No damage will 
occur to the operating program if this indication is 
ignored; it simply will not process any data from 
the affected database or file. 


error 6001: 


The database or file does not exist. 


A manipulation, such as opening a file, 
has been at- 
tempted on a file that is not in the database that 
is open currently. 


error 6002: 


Tried to open more than one database. 


Only one database can be opened at once for any pro- 
gram written using the Applications Language Li- 
brary. 


error 6004: 


Tried to open a file when no database was open. 


Before a file is opened, a database must be opened 
so the ALL can determine the existence and nature of 
the file that is being opened. 


: 
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error 6005: 


A field cannot be found. 


During the course of ALL calls, the data dictionary 
that is read when the database is opened is accessed 
to determine information about fields such as their 
name, type and location in the permanent records. 
This condition code will be returned if a field can- 
not be located in the data dictionary. 


error 6006: 


Filename has not been opened. 


Manipulation of a file has been attempted before 
opening it. 


error 6007: 


Field name cannot be found in the current file. 


When the DBSELFIELD routine is called, the field 
specified must exist in the file that is specified 
in the call. 


error 6008: 


File has not been opened. 


When the DBSELFIELD routine is called, the file that 
is specified must be open at the time of the call. 


error 6009: 


No data in the file. 


If the ALL is asked to search a file for a particu- 
lar record and discovers there are currently no 
records in the file, this error condition will be 
generated. 
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error 6010: 


Value cannot be found. 


A keyed search of a file has failed. 
The value 
which was being searched for could not be found in 
the selected index field. 


error 6011: 


End of file. 


The NEXT operation has failed because the most re- 
cently returned record from the permanent file that 
is being manipulated was the "last" record, accord- 
ing to the sorted ordering imposed by the field that 
is the currently selected index field. 


error 6012: 


Beginning of file. 


The PREVIOUS operation has failed because the most 
recently returned record from the permanent file 
that is being manipulated was the "first" record, 
according to the sorted ordering imposed by the 
field that is the currently selected index field. 


error 6014: 


No such flag value. 


The value of the flag parameter of the DBSELFIELD 
ALL routine was not one of the expected values. The 
expected values are defined in the ALL chapter of 
the INFORMIX manual, and provided for the programmer 
in a file called dbio.h, which should be installed 
in the /usr/include directory of the operating sys- 
tem. 


error 6015: 


Filename has not been opened. 


The file that is being manipulated in the DBFIND 
call must be opened before manipulation using the 
DBSELECT routine. 
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error 6016: 


No view has been set. 


A view must be set for a file before manipulation 
using the DBFIND call can be done. This view will 
establish the fields that will be moved into the 
program's buffer when reading and writing are per- 
formed. 


error 6017: 


Can't add a duplicate value - nodups option is in 
effect. 


When an index is added using DBSTATUS, the ADD INDEX 
command has two forms. 
The default form will build 
an index that requires that the information added to 
the field on which the index is based be unique in- 
formation. If this is not desired, the ALLOWING DUPS 
form of the command should be used. The 6017 error 
condition indicates that the DBADD routine attempted 
to add a record to a file which violated one or more 
of the unique indexes requirements for uniqueness. 


error 6018: 


Filename has not been opened. 


Before information can be added to a file it must be 
opened and have a view set for it using DBSELECT and 
DBSETFILEVIEW or DBSTRUCTVIEW. 


error 6019: 


No view has been set. 


Before information can be added to a file it must be 
opened and have a view set for it using DBSELECT and 
DBSETFILEVIEW or DBSTRUCTVIEW. 
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error 6020: 


There is no current record. 


The DBDELETE routine will delete the record most re- 
cently located by the DBFIND routine. This cannot be 
done if the current record has just been deleted or 
if no current record has been established. 


error 6021: 


Filename has not been opened. 


Before a record can be deleted from a file the file 
must be opened using DBSELFIELD and a view must be 
set using DBSETFILEVIEW or DBSTRUCTVIEW. 


error 6022: 


Lock was denied - deadlock avoidance. 


If this condition is returned, the program should 
attempt the lock again. 


error 6023: 


Filename has not been opened. 


Before a file can be locked, the file must be opened 
with DBSELECT and have a view set for it using 
DBSETFILEVIEW or DBSTRUCTVIEW. 


error 6024: 


Memory allocation error, out of memory. 


During certain operations, such as opening a file or 
setting up a view, memory is allocated to make room 
for Applications Language Library internal struc- 
tures. 
If memory allocation fails, the program has 
used all of its potential memory. 
~he situation can 
be remedied by keeping fewer files open at one time 
and/or creating views containing fewer fields. 
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error 6026: 


The named field must be keyed or chronological must 
be selected. 


The DBSELFIELD routine is used to set an index for a 
file so that manipulations performed on the file can 
be done using an index. 
If the chronological pri- 
mary index that is maintained by the system is used, 
the attname parameter to the call is ignored and the 
access flag should be set to ACCPRIMARY before the 
call. 


error 6028: 


Filename has not been opened. 


error 6029: 


No view has been set. 


The user must always set a view for the file before 
attempting an add, delete, or update of the file. 


error 6030: 


Can't add a duplicate value - no dups option in ef- 
fect. 


error 6031: 


Field not yet selected. 


The user has asked ALL to perform an indexed search 
using DBFIND on a field that has not yet been 
selected using DBSELFIELD. 


error 6032: 


The user does not have INFORMIX permission to add 
records. 
Change the permissions portion of the 
schema to give the user the required permission. 
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error 6036: 


The newname parameter already exists as a field or 
file name in the database. 


An alias cannot be an eXisting name in an INFORMIX 
database. 
Change the newname parameter of the 
DBALIAS call so that it is not the same as any ex- 
isting database field or file name. 


error 6037: 


The newname parameter has been used previously as an 
alias. 


Within one program, an alias cannot be used more 
than once. 
It is an error to re-use a particular 
alias name within one program. 


error 6038: 


An alias may not be an alias of an existing alias. 


The name used in the oldname parameter of the 
DBALIAS call must be the name of an eXisting INFOR- 
MIX database file. 


error 6040: 


The oldname parameter was not found as a file name 
in the database. 


The oldname parameter to the DBALIAS call must al- 
ways be an eXisting file name in the database. 
This 
code was returned because the oldname parameter 
could not be found in the database as a file name. 
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error 6041: 


The fldnum parameter is greater than the number of 
fields in the file. 


The DBNFIELD call retrieves data dictionary informa- 
tion about the nth field of a file. 
If the fldnum 
parameter of this call is greater than the number of 
fields in the file, then no information can be re- 
trieved. 


The numbering scheme for this call is zero-based. 
For the first field of a file use zero as the value 
for the fldnum parameter, one for the second, two 
for the third, etc. 


error 6043: 


Field is not a composite field type. 


The DBNCOMPOSITE call retrieves information about 
the nth part of a composite !ield. 
If the field 
name passed in the compname parameter is the name 
for a field which is not a composite type field, 
this error code is returned. 


·error 6044: 


The ncomp parameter is greater than the count of 
composite parts within the field. 


The DBNCOMPOSITE call retrieves information about 
the nth part of a composite field. 
If this routine 
is requested to retrieve information about a part of 
a composite field that does not exist, this code is 
returned. 


The numbering scheme for this call is zero-based. 
Zero should be passed as the value for the ncomp 
parameter for information about the first field, one 
for the second, etc. 


error 6045: 


Access permission denied. 


The user does not have the required INFORMIX access 
permissions to access the file. 
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error 6046: 


File not opened exclusively. 


While adding or deleting indexes for fields, ex- 
clusive access is required on the pertinent file. 
To get exclusive access to a file, 
open it using the 
DBSELECT call with EXCLUSIVE added arithmetically to 
the FILEOPEN parameter [e.g., 
dbselect(FILEOPEN+EXCLUSIVE, filename)]. 


error 6047: 


Index already exists. 


If an attempt is made to add an index for a field 
that already has an index built for it, the DBADDIN- 
DEX call will return this error code. 
No damage oc- 
curs to either the file or program when this error 
is returned. 
Processing can continue normally. 


error 6048: 


A duplicate key value was found while adding an in- 
dex for which NODUPS was specified. 


When NODUPS is specified as the dupsorno parameter 
to the DBADDINDEX call, the user is requesting that 
an index which does not allow duplicate key values 
be created. 
If duplicate key values are found in 
the data while adding a NODUPS index, this code is 
returned. 
No index has been added if this code is 
returned. 
Be sure that the value being passed as 
the dupsorno parameter is the intended value, or 
check through the data for the pertinent field and 
eliminate duplicate values. 


error 6049: 


The current user does not have the CONTROL ACCESS 
that is needed to add or delete and index on a 
field. 


To add or delete indexes for fields in an INFORMIX 
database a special access privilege is required. 
This access is called CONTROL ACCESS. 
See the dis- 
cussion of User Access Privileges in the DBBUILD 
chapter. 
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error 6050: 


Bad key description: internal error 


This error should never occur under normal operating 
conditions. 
It is likely that some of the user pro- 
gram code is writing over the structures used by the 
Applications Language Library held in memory. 
Check 
the user program code for badly initialized 
pointers. 


error 6051: 


Composite field names are not allowed in DBVIEW. 


You can, however, use the component fields of a com- 
posite field in DBVIEW. 


error 6052: 


Not all of the composite field is contained in the 
current view of this file. 
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C-ISAM ERRORS 


The following is a list of error codes which may be 
returned from Applications Language Library rou- 
tines. 
These errors originate from the C-ISAM ac- 
cess method. 


error -1: 


Internal error. 


This error can 
not expected. 
global integer 
code. 
See the 


error 100: 


be returned by an ALL routine, but is 
When this occurs, the value of the 
iserrno will contain the C-ISAM error 
following list of C-ISAM error codes. 


An attempt was made to add a duplicate value to an 
index via iswrite, isrewrite, isrewcurr or isaddin- 
dex. 


error 101: 


An attempt was made to perform some operation on a 
C-ISAM file that was not previously opened using the 
isopen call. 


error 102: 


One of the arguments of the C-ISAM call is not 
within the range of acceptable values for that argu- 
ment. 


error 103: 


One or more of the elements that make up the key 
description is outside of the range of acceptable 
values for that element. 


error 104: 


The maximum number of files that may be open at one 
time would be exceeded if this request were pro- 
cessed. 
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error 105: 


The format of the C-ISAM file has been corrupted. 


error 106: 


In order to add or delete an index, the file must 
have been opened with exclusive access. 


error 107: 


The record or file requested by this call cannot be 
accessed because it has been locked by another user. 


error 108: 


An attempt was made to add an index that has been 
defined previously. 


error 109: 


An attempt was made to delete the primary key value. 
The primary key may not be deleted by the isdelindex 
call. 


error 110: 


The beginning or end of file was reached. 


error 111: 


No record could be found tnat contained the request- 
ed value in the specified position. 


error 112: 


This call must operate on the current record. 
One 
has not been defined. 


error 113: 


The file is exclusively locked by another user. 
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error 114: 


The file name sent to a C-ISAM routine is too long. 
This is an internal error. 


error 115: 


Cannot create a lock file. 
Be sure that access to 
the C-ISAM directory is read, write, and execute for 
everyone. 


error 116: 


Memory allocation error. 
No memory is left. 
Make 
views smaller or open fewer files at one time. 


error 117: 


Bad custom collating. 
This is an internal error. 
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I. 
Introduction 


ENTER1 is INFORMIX's line-oriented interactive 


data entry and update program. 
You can use it to 
add, update, and delete data on a record-by-record 
basis. 
ENTER1 is similar to ENTER2, but is designed 
for use with hard copy terminals or other terminals 
which cannot use ENTER2. 


ENTER1 is not provided with MS-DOS versions of 
INFORMIX. 


The following database is assumed in the exam- 
ples in this chapter. 


customers file 


cname 


Brooks, B. 
Field, W. 
Robin, R. 
Hart, 
W. 
Court, S. 
English, D. 


orders file 


oname 


Brooks, B. 
Brooks, B. 
Robin, R. 
Hart, 
W. 


Robin, R. 
Court, S. 
Court, S. 
English, D. 
English, 
D. 


address 


7 Apple Rd. 
43 Cherry Ln. 
12 Heather Ct. 
65 Lark Rd. 
56 Blossom Rd. 
82 Alpine Rd. 


item 


Work Bench 
Saw 
Work Bench 
File 
Hammer 
Saw 
File 
File 
Hammer 


balance 


10.50 
0.00 
23.45 
43.00 
0.00 
0.00 


quantity 


5 
1 
3 
3 
8 
3 
5 
1 
2 


Figure 1. The stores database 
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II. 
Calling ENTER1 


You can call ENTER1 
f~om the Master Menu by 
selecting Option 8. 
If you have already established 
a current database, 
ENTER1 automatically selects it. 
Then ENTER1 lists the files in the database and asks 
you to choose one. 
If there is only one file in the 
database, ENTER1 automatically selects it as the 
current file. 


If you have not established a current database, 
ENTER1 asks you to select one. 
Then it prompts you 
to select a file. 


You can also call ENTER1 from the operating 
system. 


Once it is loaded, 
ENTER1 asks you to select a 
database. 
Then it lists the files in the database 
and asks you to choose one. 
Your screen will look 
like Figure 2. 


When you call ENTER1 from the operating system, 
you can specify a database, a file, and a field. 
For example, to call ENTER1 and make stores the 
current database, customers the current file, and 
cname the current field, type: 


%enter1 stores customer cname 


If you select a current database and a file but 
not a field, 
ENTER1 automatically selects the 
current field. 
It chooses the first indexed field, . 
or if none of the fields are indexed, the first 
field listed in the schema. 
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% enter1 


ENTER1 Data Entry Program 
INFORMIX 
version 3.2 
Copyright (C) 1981, 1982, 1983 
Relational Database Systems, Inc. 
Software Serial Number RDS-000001 


Type 'hI if help is desired. 


Please enter' the database you would like to select. 
> stores 


The database "stores" 
has been selected successfully. 


The files in the database "stores" are listed below. 


customers 


Enter your choice. 
> customers 


orders 


The file "customers" has been selected successfully. 
The field "cname" is now the current field. 


Figure 2. Calling ENTER1 from the operating system, 
and selecting a database and a file. 
ENTER1 au- 
tomatically selects the current field. 
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III. 
Command Summary 


The ENTER1 prompt is the symbol >. 


You can give a command either by 
typing its 
first letter (uppercase or lowercase) or by typing 
the entire command name. 
Since SELECT and SAME have 
the same first character, 
SELECT is abbreviated as 
SEL. 
SAME is abbreviated as S. 


Once you enter a command, 
ENTER1 prints a mes- 
sage to verify that it was received. 
You can abort 
any command by pressing DELETE or RUBOUT. 


The ADD command is used to add new records to 
the file. 
The FIND command is used to locate and 
print a record based on the contents of the current 
field. 


You can change the current field at any time 
with the FIELD option of the SELECT command. 
You 
can also use SELECT to change the current file or 
database. 


If the current field has an index, you can use 
the NEXT and PREVIOUS commands to browse through the 
file by the sorted ordering of this field. 
If the 
current field does not have an index, the NEXT and 
PREVIOUS commands move through the file in the order 
the records were entered (the "chronological" order- 
ing) or in the primary key ordering if a primary key 
is specified. 
In this case, you can use the SAME 
command to find the next record in the file that 
satisfies the most recent FIND command. 


Afte~ a record has been located and printed 
with any of these commands, you can remove it from 
the file with the DELETE command or modify it with 
the UPDATE command. 


The HELP command lists all of the available 
commands and their formats. 


The BYE command closes all files in use and 
terminates the ENTER1 session. 
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IV. 
Iaportant Features 


IV.A. 
Searches 


If you search a file on an indexed field, 
ENTER1 responds immediately, no matter how large the 
file. 


ENTER1 can also search non-indexed fields. 
This type of search (called a "sequential search") 
may take some time. 


To abort the search, press DELETE. 
To add an 
index, use the ADD INDEX command from DBSTATUS or 
INFORMER. 


By definition, an index is a sorted ordering of 
the records in a file. 
If the current field has an 
index, you can use the FIND FIRST, FIND LAST, 
NEXT 
and PREVIOUS commands to browse the file in sorted 
order. 
When you change the current field with the 
SELECT command, the sorted ordering used by "these 
commands changes as well. 


ENTER1 can search a CHARACTER field even if you 
know only the first few characters of the value you 
are searching. 


This type of search, called a "generic search," 
is useful if you do not remember the entire value or 
if the value entered in the database is spelled in- 
correctly and cannot be found when you give the en- 
tire value. 


If you want to find only records that match the 
search value exactly, the quoted string 
u~ed in the 
FIND command should contain the same number of char- 
acters as the field in the database. 
You can find 
out the length of a character field by using the 
PRINT SCHEMA command. 
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IV.B. 
Data Checking 


When you enter data using the ADD and UPDATE 
commands, ENTER1 checks the database dictionary for 
the type and length of the field. 
If the value you 
enter does not correspond to the defined field type 
and length, ENTER1 displays an error message and 
pr.ompts you to try again. 


Fo~ example, if the field is defined as an IN- 
TEGER field and you enter characters, 
ENTER1 will 
not accept your input. 
If the field is a CHARACTER 
field, 
ENTER1 truncates input longer than the de- 
fined length. 
If the input is shorter than the de- 
fined length, 
ENTER1 adds blanks to the end of the 
input. 


IV.C. 
Concurrency Control 


Concurrency control is necessary in a multi- 
user environment to 
ens~re that two users do not try 
to update the same record at the same time. 


ENTER1 "locks" a record while it is being up- 
dated. 
A locked record can be viewed by other 
users, but not updated. 
If you try to update a 
record that another user is updating, 
ENTER1 
displays the message "Record or file is locked by 
another user." 
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V. 
Commands and Their Use 


V.A. 
The· FIND Command 


> find "search-value" 


> find 10.20 


> f 
45 


The FIND command allows you to locate records 
based on the value of the current field. 
If the 
current field is a CHARACTER field, you must enclose 
the search value in double quotes. 
If the field is 
any other type, do not enclose the search value in 
quotes. 


You can use FIND to search both indexed and 
non-indexed fields, but the results differ slightly 
if a match is not found. 
If the current field has 
an index and ENTER1 cannot find a record exactly 
corresponding to the specified search value, it 
prints a message to that effect and then prints the 
record which has a value just higher than the search 
value. 
If the current field does not have an index, 
ENTER1 performs a sequential search and prints a 
message reminding you that a search is underway. 
If 
ENTER1 cannot find a record which exactly matches 
the search val ue, it prints the error message "The 
end of the file has been reached." ENTER1 makes no 
attempt to print the "closest" record when the field 
being searched is not indexed. 


You can abort a search with the DELETE or 
RUBOUT key. 


You can use FIND to perform a generic search, 
as described in section IV.A. 
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> find "Field, V." 


FIND 


cname 
address 
balance 


Field, 
V. 


43 Cherry Ln. 
0.000000 


> select field address 


The file "customers" has been selected successfully. 
The field "address" is now the current field. 


> find "65 La" 


FIND 


A linear search will now be made. 


The search may take some time. 


cname 
address 
balance 


Hart, 
W. 


65 Lark Rd. 
43.000000 


> select field balance 


The file "customers" has been selected successfully. 
The field "balance" is now the current field. 


> find 23.45 


FIND 


A linear search will now be made. 
The search may take some time. 


cname 
address 
balance 


INFORMIX 


Robin, 
R. 
12 Heather Ct. 
23.450000 
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V.B. 
The FIND FIRST Command 


> find first 


> f first 


> f 
f 


The FIND FIRST command is usually used with 


fields that 
ha~_indexes. 
FIND FIRST displays the 
record with the lowest value in the current field. 


If you use FIND FIRST when the current field 
does not have an index, 
ENTER1 displays the first 
record in the file according to the chronological or 
primary key ordering. 


> find first 


FIND FIRST 


cname 
address 
balance 


12 


Brooks, B. 
7 Apple Rd. 
10.500000 
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V.C. 
The FIND LAST Command 


> find last 


> f last 


> f 
1 


Like FIND FIRST, FIND LAST operates on the 
currently selected field. 
If the current field has 
an index, FIND LAST displays the record with the 
highest value in the current field. 
If FIND LAST is used when the current field 
does not have an index, ENTER1 displays the last 
record in the chronological or primary key ordering. 


> find last 


FIND LAST 


cname 
address 
balance 


INFORMIX 


Robin, R. 
12 Heather Ct. 
23.450000 
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V. D. 
The NEXT Command 


> next 


> n 


When used on an indexed field, the NEXT command 
displays the record with the next higher value than 
the last record read. 
The ordering is based on the 
index for the current field. 


When used on a non-indexed field, 
NEXT prints 
the next record in the file according to the chrono- 
logical or primary key ordering. 


> f first 


FIND FIRST 


cname 
address 
balance 


> n 


NEXT 


cname 
address 
balance 


> n 


NEXT 


cname 
address 
balance 


> n 


NEXT 


cname 
address 
balance 


> n 


14 


Brooks, B. 
7 Apple Rd. 
10.500000 


Court, S. 
56 Blossom Rd. 
0.000000 


English, D. 
82 Alpine Rd. 
0.000000 


Field, 
W. 


43 Cherry Ln. 
0.000000 
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NEXT 


cname 
address 
balance 


> n 


NEXT 


cname 
address 
balance 


> n 


NEXT 


Hart, 
W. 


65 Lark Rd. 
43.000000 


Robin, 
R. 
12 Heather Ct. 
23.450000 


The end of the file has been reached. 
See error number 3017. 
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V.E. 
The NEXT integer Command 


> next 2 
> n 2 


If you give an integer ("n") after the NEXT 
command, 
NEXT is executed "n" times. 
In other 
words, ENTER1 skips "n" records and prints the last 
one found. 


The NEXT integer command uses the sorted order- 
ing of the current field if it is indexed or the 
chronological or primary key ordering if the current 
field is not indexed. 


> find first 


FIND FIRST 


cname 
address 
balance 


> n 2 


NEXT 


cname 
address 
balance 


> n 3 


NEXT 


cname 
address 
balance 


> n 


NEXT 


Brooks, B. 
7 Apple Rd. 
10.500000 


English, D. 
82 Alpine Rd. 
0.000000 


Robin, R. 
12 Heather Ct. 
23.450000 


The end of the file has been reached. 
See error number 3017. 
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V.F. 
The PREVIOUS Command 


) previous 


) 
p 


The PREVIOUS command is the complement of the 
NEXT command. 
When used on an indexed field, it 
displays the record with the next lower value than 
the last record read. 


The ordering is based on the index for the 
current field. 
When used on a non-indexed field, 
PREVIOUS prints the previous record in the file ac- 
cording to the chronological or primary key order- 
ing. 


) find last 


FIND LAST 


cname 
address 
balance 


) 
P 


PREVIOUS 


cname 
address 
balance 


) 
P 


PREVIOUS 


cname 
address 
balance 


) P 


PREVIOUS 


cname 
address 
balance 
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Robin, R. 
12 Heather Ct. 
23.450000 


Hart, 
W. 


65 Lark Rd. 
43.000000 


Field, w. 
43 Cherry Ln. 
0.000000 


English, D. 
82 Alpine Rd. 
0.000000 
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> P 


PREVIOUS 


cname 
address 
balance 


> P 


PREVIOUS 


cname 
address 
balance 


> P 


PREVIOUS 


Court, S. 
56 Blossom Rd. 
0.000000 


Brooks, B. 
7 Apple Rd. 
10.500000 


The beginning of the file has been reached. 
See error number 3019. 
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V.G. 
The PREVIOUS integer Command 


> previous 3 


> P 3 


The PREVIOUS integer command is exactly analo- 
gous to the NEXT integer command. 
While the NEXT 
integer command steps through the file in ascending 
order, the PREVIOUS integer command moves in 
descending order. 


> f 
1 


FIND LAST 


cname 
address 
balance 


> p 3 


PREVIOUS 


cname 
address 
balance 


> p 2 


PREVIOUS 


cname 
address 
balance 


> P 


PREVIOUS 


Robin, R. 
12 Heather Ct. 
23.450000 


English, D. 
82 Alpine Rd. 
0.000000 


Brooks, B. 
7 Apple Rd. 
10.500000 


The beginning of the file has been reached. 
See error number 3019. 
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V. H. 
The SAME Command 


> same 


> s 


To continue searching for other records that 
match the same search value, use the SAME command. 
You can use SAME repeatedly until you reach the end 
of the file to find all of the records that satisfy 
the conditions of the original FIND command. 


> select field balance 


The file "customers" has been selected successfully. 
The field "balance" is now the current field. 
> find 0.0 


FIND 


A linear search will now be made. 
The search may take some time. 


cname 
address 
balance 


> same 


SAME 


cname 
address 
balance 


> s 


SAME 


cname 
address 
balance 


> s 


SAME 


Field, W. 
43 Cherry Ln. 
0.000000 


Court, S. 
56 Blossom Rd. 
0.000000 


English, D. 
82 Alpine Rd. 
0.000000 


The end of the file has been reached. 
See error number 3017. 
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V. I • 
The ADD Command 


> add 


> a 


When you give the 
ADD command, 
ENTER1 prompts 
you for each field with the field's name and a dou- 
ble prompt (»). 
Enter the data after the prompt. 


ENTER1 checks the type and length and re- 
prompts you if the input is incorrect. 
You cannot 
continue to the next field until you enter the data 
correctly. 


If the input is correct, 
ENTER1 prompts you 
with the next field name. 
When you have entered 
data in all the fields, 
ENTER1 adds the record to 
the database. 


You can terminate the ADD command with the 
DELETE or RUBOUT key. 


> add 


ADD 


cname 
» 
Brooks, B. 


address 
» 
7 Apple Rd. 


balance 
» 
10.50 


The record is: 


cname 
address 
balance 


Brooks, B. 
7 Apple Rd. 
10.500000 


The new record has been added successfully. 
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V.J. 
The DELETE Command 


> delete 


> d 


To delete a record, first find and display it 
on the terminal using the FIND, NEXT, PREVIOUS, or 
SAME command. 
Then enter 'd' or 'delete' in 
response to the prompt. 
When ENTER1has deleted the 
record, it prints the message, 
"The current record 
has been deleted." 


> find first 


FIND FIRST 


cname 
address 
balance 


> d 


DELETE 


Brooks, B. 
7 Apple Rd. 
10.500000 


The current record has been deleted. 
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V.K. 
The UPDATE Command 


> update 


> u 


Before you can change a record, you must 
display it on the screen with a FIND, 
NEXT, PREVI- 
OUS, or SAME command. 
Then you can execute the UP- 
DATE command by typing u. 


For each field in the current record, 
UPDATE 
prints the field's name and its contents. 
It then 
prompts for input to replace these contents. 
If you 
do not want to change the field, press RETURN. 
If 
you want to change the data in the field, type the 
new data and press RETURN. 


When you have finished updating all of the 
fields, 
ENTER1 displays the entire record and asks 
whether it is correct. 
If you respond "yes," ENTER1 
wri tes the record to the file. 
If you respond "no," 
ENTER1 returns to the prompting sequence with the 
most current version of the record. 
You can use the 
DELETE or RUBOUT key at any point to abort the com- 
mand. 
ENTER1 makes no changes to the database un- 
less the command completes. 


If you give the UPDATE command for a record 
that another user is already working on, ENTER1 
displays the message, 
"Record or file is locked by 
another user." You will not be allowed to change the 
record until the other user has finished updating 
it. 
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> find first 


FIND FIRST 


cname 
address 
balance 


> u 


UPDATE 


cname 
Brooks, B. 
» 


address 
7 Apple Rd. 
» 
21 Maple Pl. 


balance 
10.500000 
» 


Brooks, B. 
7 Apple Rd. 
10.500000 


The updated record is: 


cname 
address 
balance 


Brooks, B. 
21 Maple Pl. 
10.500000 


Is the record correct (yin)? 
y 


The record has been updated successfully. 
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V.L. 
The SELECT DATABASE Co..and 


> select database db-name 
> sel db db-name 


You can change the database' you are working 
with during an ENTER1 session with the SELECT DATA- 
BASE command. 


> select database stores 


ACCESS DATABASE 


The database "stores" has been selected successfully. 


The files in the database "stores" are listed below. 


customers 


Enter your choice. 
> 


orders 


V.M. 
The SELECT FILE Command 


> select file file-name 


> sel file file-name 


You can change the current file during an 
ENTER1 session with the SELECT FILE command. 
Since 
no two files can contain the same field, changing 
files also changes the current field. 


> select file orders 


The file "orders" has been selected successfully. 
The field "oname" is now the current field. 
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V.N. 
The SELECT FIELD Command 


> select field field-name 


> sel field field-name 


When you select a file, 
ENTER1 automatically 
selects a current field. 
You can change the current 
field with the SELECT FIELD command. 
If the field 
you select is in another file, the current file 
changes also. 


> select field cname 


The file "customers" has been selected successfully. 
The field "cname" is now the current field. 


V. O. 
The PRINT SCHEMA Command 


> pr int 
schema 


The PRINT SCHEMA command displays the schema of 
each file in the current database. 


> print schema 


PRINT SCHEMA 


database stores 


file customers 


field cname 
field address 
field balance 


file orders 


field oname 
field item 
field quantity 
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type char 15 
type char 15 
type double 


type char 15 
type char 15 
type integer 


permission all 


permission all 
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V.P. 
The PRINT STATUS Command 


> print status 


The PRINT STATUS command displays general in- 
formation about each file in the current database, 
including the length of its records, the number of 
records, and the existence and state of indexes and 
audi t trails. 


> print status 


PRINT STATUS 


database stores 


file customers 


data record length 
number of records 
number of indexes 
cname 
address 
balance 


file orders 


data record length 
number of records 
number of indexes 
oname 
item 
quantity 
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3 
duplicates not allowed 
duplicates allowed 
duplicates allowed 


36 
9 
3 
duplicates allowed 
duplicates allowed 
duplicates allowed 
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V.Q. 
The HELP Command 


> help 
> h 


The HELP command lists all of the ENTER1 com- 
mands along with a brief explanation of each. 
HELP 
also displays the name of the current database, file 
and field. 


> h 


HELP 


You may terminate all commands by pressing the 
RUBOUT or DELETE keys. 


The current database is "stores". 
The current file is "customers". 
The current field is "cname". 


Type carriage return to continue the help command, 
or DELETE to abort it. 


> 


28 


Command 


SELECT DATABASE db-name 
or 
SELECT FILE file-name 
or 
SELECT FIELD field-name 
or 
ADD 
BYE 
DELETE 
FINO 


FINO FIRST 
FINO LAST 
HELP 
NEXT 
NEXT integer 
PRINT SCHEMA 
PRINT STATUS 
PREVIOUS 
PREVIOUS integer 
SAME 
UPDATE 


Command Syntax 


SELECT DATABASE db-name 
SEL DB db-name 
SELECT FILE file-name 
SEL FILE file-name 
SELECT FIELD file-name 
SEL FIELD field-name 
ADO or A 
BYE or B 
DELETE or 0 
FINO value or F value (character values 
must be quoted using the" character) 
FINO FIRST, F FIRST or F F 
FINO LAST, F LAST or F L 
HELP or H 
NEXT or N 
NEXT integer or N integer 
PRINT SCHEMA 
PRINT STATUS 
PREVIOUS or P 
PREVIOUS integer or P integer 
SAME or S 
UPDATE or U 
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V.R. 
The BYE Command 


> bye 


> b 


The BYE' command closes all files that are open 
and ends the ENTER1 session. 


> bye 


BYE 


Program over. 
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v. 
Appendix -Error Messages 


error 3000: 


The current command is not valid. 
Please try again. 


The commands of ENTER1, along with their legal ab- 
breviations, are listed in the ENTER1 chapter of the 
INFORMIX manual, as well as in the interactive HELP 
command. 
One of the legal commands must be used. 


error 3001: 


An illegal integer value has been entered. 


INFORMIX integers must be in the range -32760 
through +32760. 


error 3003: 


This identifier exceeds the maximum length allowed, 
which is 50 characters. 


The name of the database, the files, and the fields 
are all considered identifiers. 
Any identifier may 
be up to 50 characters in length. 
In the case of 
fields, alISO of these characters are significant 
in comparisons. 


error 3004: 


This quoted string exceeds the maximum length al- 
lowed, which is 50 characters. 


When quoted strings are used in-INFORMIX interactive 
languages, they must be less than or equal to 50 
characters in length. 


error 3005: 


A quote has been found for which there is no match- 
ing quote. 


When quoted strings are used in INFORMIX interactive 
languages, they must begin and end on the same line. 
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error 3006: 


An unidentifiable character sequence or a non- 
printing character has been found. 


There are certain characters that can be transmitted 
to computers that are not visible on computer termi- 
nals. 
They are generated by holding down the CON- 
TROL key and striking an ordinary character, much 
like a capital letter is generated by holding down 
the SHIFT key. 
These characters are usually used to 
tell the computer to perform various acts. 
For ex- 
ample, many operating systems use the CONTROL-D se- 
quence to indicate the end of a user's session at 
the terminal. 
However, these characters have no 
place in computer programs such as the files that 
hold DBBUILD file descriptions. 
Most text editors 
have facilities for visualizing the invisible con- 
trol characters, and allowing the user to eliminate 
them from the program. 
This should be done before 
compilation is attempted again. 


error 3008: 


The current record cannot be added because it would 
necessitate adding a duplicate value for a key for 
which 'nodup' was specified. 


DBSTATUS can be used to create indexes on one or 
more fields. 
These indexes can be created so that 
duplicate values are either allowed or disallowed. 
The default is to disallow duplicate values. 
The 
command ADD INDEX FOR field ALLOWING DUPS must be 
used in DBSTATUS to create an index where duplicates 
are allowed. 
ENTER1 will enforce the duplicates al- 
lowed and disallowed instructions given to DBSTATUS. 


error 3010: 


The field specified could not be found for the data- 
base selected. 


An identifier was typed to ENTER1 where a field name 
was expected. 
Although ENTER1 searched the database 
data dictionary, the identifier typed could not be 
found. 
The DBSTATUS program can be used to print 


the database schema in order to verify the existence 
and proper spelling of identifiers such as file 
names and field names. 
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error 3011: 


The file specified could not be found in the data- 
base selected. 


An identifier was typed to ENTER1 where a file name 
was expected. 
Although ENTER1 searched the database 
data dictionary, the identifier could not be found. 
The DBSTATUS program can be used to print the data- 
base schema in order to verify the existence and 
proper spelling of identifiers such as file names 
and field names. 


error 3012: 


An internal system error has occurred. 


This message indicates that something is unexpected- 
ly wrong with either the ENTER1 program or the 
structure of the database that is currently being 
examined. 
The structure of the database could be 
jeopardized by undetected operating system failure, 
or numerous other unlikely causes. 
The database 
should be regenerated and the transaction attempted 
once again. 
A database can be regenerated by un- 
loading all of the files, erasing the database, 
recompiling all of the schema files, and then re- 
loading all of the files. 
If it is suspected that 
just one of the indexes is damaged, this index can 
be removed and re-added without regenerating the en- 
tire database. 


error 3014: 


This command requires a current record - one has not 
been defined. 
. 


Several of the ENTER1 commands require that a record 
be located before they make any sense. 
This is true 
of the DELETE and UPDATE commands. 
A current record 
can be established by finding a record with the 
FIND, FIND FIRST or FIND LAST commands if the field 
is indexed. 
Otherwise, the simple FIND command or 
the SAME command can be used. 


: 
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error 3015: 


The database specified could not be found. 
Please 
try again. 


When ENTER1 is run, the database to be examined must 
be in the current directory. 
This means that before 
ENTER1 is run, the operating system command to list 
files must reveal the database files that actually 
contain data. 
These files all begin with the first 
four characters of the database name. 


error 3016: 


The file specified could not be found. 
Please try 
again. 


An identifier was typed to ENTER1 where a file name 
was expected. 
Although ENTER1 searched the database 
data dictionary, the identifier could not be found. 
The DBSTATUS program can be used to print the data- 
base schema in order to verify the existence and 
proper spelling of identifiers such as file names 
and field names. 


error 3017: 


The end of the file has been reached. 


When the current field is an indexed field, the NEXT 
command may be used. 
This command steps through the 
data in the file in the sorted ordering determined 
by the current field. 
When the next record is re- 
quested, but the most recently displayed record was 
the last record in the sorted ordering, this is con- 
sidered the "end of the file." 
If the NEXT command 
is used with an integer, this message indicates that 
the number of records indicated in the command could 
not be skipped before running out of records. 


error 3018: 


This command cannot be used on a non-key field. 


Commands such as FIND FIRST, FIND LAST, 
NEXT and 
PREVIOUS only have meaning when the current field 
has had an index built for it with DBSTATUS. 
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error 3019: 


The beginning of the file has been reached. 


See error 3017 above. 
(Error 3019 will occur with 
the PREVIOUS command.) 


error 
3020~ 


NEXT or PREVIOUS can only be used after a successful 
keyed search. 


These commands can only be used if a current record 
has been located with the FIND FIRST, FIND LAST, or 
simple FIND command and the current field has had an 
index built for it with DBSTATUS. 


error 3021: 


A record cannot be found which corresponds to the 
currently specified search value. 


The simple FIND command takes an argument which is 
the sUbject of ENTER1's search. 
This message will 
print if the search for an exact match has failed. 


error 3022: 


This is an internal system error. 


error 3023: 


SAME can only be used after a successful non-key 
search. 


Just as NEXT and PREVIOUS only have meaning when the 
current field has an index built for it, the SAME 
command only makes sense when the current field does 
not have an index. 
When the current field has no 
index and the simple FIND command is executed, a 
sequential search of the file is performed by 
ENTER1. 
If a record is found that meets the 
qualification of the search, it is printed. 
Howev- 
er, it may not be the only record in the file to 
meet the qualification. 
If another FIND command 
were executed, the search would begin at the begin- 
ning of the file once again, and the same record 
would be found. 
To continue the search through the 
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file and to find all of the records that meet the 
search criteria, the SAME command should be used re- 
petitively until the end of the file is reached. 


error 3024: 


There is no data for this file. 


If ENTER1 is asked to search a file for a particular 
record and discovers that there are no records in 
the file, this message will be generated. 


error 3025: 


A record corresponding to the current search value 
cannot be found between the current record and the 
end of the file. 


The SAME command has run out of duplicate search 
values. 
(See error 3023.) 


error 3026: 


The data for the field must be of the type speci- 
fied. 


The data being entered must be of the type defined 
by the schema for the current field. 
Integer and 
double fields may only have numbers entered. 


error 3027: 


An illegal double value has been entered. 


The maximum number of significant digits for a dou- 
ble is 15. 
The number of characters used to express 
the precision of a double precision floating point 
number is limited by INFORMIX to 15. 
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error 3028: 


The current record is locked by another user and 
therefore cannot be deleted or updated now. 


Another user is accessing the same record and so it 
has been temporarily locked. 


error 3029: 


An illegal double value has been entered. 


The maximum number of significant digits for a dou- 
ble is 15. 
The number of characters used to express 
the precision of a double precision floating point 
number is limited by INFORMIX to 15. 


error 3030: 


The current record has already been deleted. 


Issuing a DELETE command is asking ENTER1 to delete 
the most recently printed record from the database. 
Since the same record cannot be deleted twice, two 
DELETE commands may not be issued consecutively. 


error 3031: 


The current record was deleted or changed by another 
user. 


When others are on the system during database 
modifications, a record will occasionally be deleted 
by one user while another user is in the process of 
going through the update prompts for that record. 
If this occurs, 
ENTER1 detects the fact that the 
record that was being updated by one user was delet- 
ed by the other. In this case ENTER1 honors the 
deletion, thus not re-adding the record that was up- 
dated. 
If the record really should exist, it can be 
re-added. 
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error 3032: 


The record was deleted by another user between the 
time it was found and the request for deletion was 
issued. 


Another user is accessing the same file and deleted 
the record before your delete command was received 
by INFORMIX. 


error 3033: 


The file is exclusively locked by another user and 
cannot be accessed now. 


A user is accessing the same file and has restricted 
access so that no other users may access the file. 


error 3034: 


Permission not granted for reading this file. 


error 3035: 


Permission not granted for updating this file. 


error 3036: 


Permission not granted for adding records to this 
file. 


error 3037: 


Permission not granted for deleting records from 
this file. 


error 3038: 


Read only permission allowed on this file. 
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I. 
Introduction 


ENTER2 is one of INFORMIX's two screen-oriented 
interactive data entry and query programs. 
It pro- 
vides a subset of the functions available in PER- 
FORM. 
With ENTER2, you can search a file on the 
basis of the value in a single field or browse 
through a file a record at a time. 
You can update 
data on a record-by-record basis. 


You give ENTER2 commands by typing a single 
character. 
You need not press the RETURN key. 


This chapter uses as an example the realty da- 
tabase, which has two files, listings and agents. 
The schemas for these two files are shown in Figures 
1 and 2 on the next page. 
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database real ty 


f'ile listings 


f'ield listing number 
type integer 
f'ield address- 
type character 
length 15 
f'ield city 
type character 
length 10 
f'ield f'ootage 
type integer 


f'ie ld bedrooms 
type integer 


f'ie ld baths 
type integer 


f'ield lot size 
type double--- 


f'ield corner lot 
type character 
length 


!'ie ld schools 
type character 
length 
f'ield asking_price 
type money 
f'ield sales price 
type money 
f'ield broker 
type character 
length 15 
index dups 


f'ield li sting_note 1 
type character 
length 45 


end 


Figure 1. Schema for the listings file. 


database real ty 


f'ile agents 


f'ield agent number 
f'ield agent-name 
f'ield agent-address 
f'ield agent-city 
f'ield agent-zip code 
f'ield agent-phone 
f'ield agent:salary 


end 


type integer 
type character 
type character 
type character 
-type long 
type character 
type money 


length 15 
index 
length 20 
length 10 


length 8 


Figure 2. Schema for the agents file. 
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II. 
Calling ENTER2 


You can call ENTER2 from the Master Menu by 
selecting Option 7. 
If you have already established 
a current database, ENTER2 automatically selects it. 
Then ENTER2 lists the files in the database and asks 
you to choose one. 


You can also call ENTER2 from the operating 
system. 
Once ENTER2 is loaded, it asks you to 
select a database. 
Then it lists the files in the 
database and asks you to choose one. 
Your screen 
will look like Figure 3. 


If there is only one file in a database, ENTER2 
selects it automatically. 


When you call ENTER2 from the operating system, 
you can specify a database, a file, 
and even a 
field. 
For example, to use ENTER2 with the listings 
file of the realty database, type 


%enter2 realty listings 
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% enter2 


ENTER2 Data Entry Program 
INFORMIX version 3.2 


Copyright (C) 1982, 1983 Relational Database Systems, Inc. 
Software Serial Number RDS-000001 


Please enter the database you would like to select. 
> realty 


The files in the database "realty" are listed below. 


listings 


Enter your choice. 
> listings 


agents 


Figure 3. Calling ENTER2 and selecting a database 
and file. 
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III. 
The ENTER2 Screen 


Once you have selected a database and a file, 
ENTER2 displays the "skeleton" of an empty record. 
The field names are at the left of the screen. 
A 
display area for data, enclosed in square brackets, 
follows each field name. 


The size of each field's display area is deter- 
mined by its type. 
For CHARACTER fields, 
ENTER2 
provides a display. area corresponding to the length 
assigned in the schema. 


Figure 4 shows an ENTER2 screen for the 
listings file. 


The top line of the screen lists the ENTER2 
commands. 
You give an ENTER2 command by typing its 
first letter, either in uppercase or lowercase. 
If 
you type a character which is not a command, the 
terminal" responds with a beep. 


Some commands require you to give additional 
information. 
For example, the DELETE command asks 
you to confirm the one-character keystroke. 
You can 
abort any command that occurs in more than one step 
by pressing the DELETE key. 
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eoaaanda, Find Next 
Pre~ioua Update Add 
Del~te Select led:ew Bye ? 


1iatin9-ftumber 
[ 
addreaa 
[ 
city 
[ 
footage 
! 


~:~~~oms 
[ 
lot-aize 
[ 
cornerJot 
[ J 


achoola 
[ J 
aakin9-Price 
; 
anles-price 
i 


broker 
[ 


Uatin<J-l\otel 
, 
1iatin<J-l\ote' 
! 
1iatin<J-l\ote3 
, 


Figure 4. The skeleton of a record in the listings 
file. 
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IV. 
Command Summary 


The FIND command locates and displays a record 
based on the contents of one of its fields. 
If the 
field is indexed, the NEXT and PREVIOUS commands 
find records according to a sorted ordering of this 
field. 


After ENTER2 has located and displayed a 
record, you can remove it from the file with the 
DELETE command or modify it with the UPDATE command. 
To add new records to the file, use the ADD command. 


When you call ENTER2, you must select a current 
database and a file. 
ENTER2 automatically selects a 
current field by looking for the first field that is 
indexed. 
If no fields in the current file are in- 
dexed, ENTER2 makes the first field in the schema 
the current field. 


The current field is used with the FIND, 
NEXT, 
and PREVIOUS commands. 
To FIND a record you fill in 
the current field with a value. 
ENTER2 searches the 
file and displays the first record with that value. 
NEXT and PREVIOUS display records that are the next 
or previous according to the sorted order of the 
current field if it is indexed. 
If the current 
field is not indexed, 
NEXT and PREVIOUS use the pri- 
mary key order (which corresponds to the order of 
entry unless there is a user-declared primary key). 


To change the current database, file, or field, 
you can use the SELECT command at any time. 


REDRAW redisplays a screen 
i~ it has been gar- 
bled during an ENTER2 session. 


The BYE command terminates the ENTER2 session. 
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V. 
Important Features 


V.A. 
Searches 


If you search a file on a field that is in- 
dexed, 
ENTER2 responds immediately, no matter how 
large the file. 


ENTER2 can also search non-indexed fields. 
However, this type of search (called a sequential 
search) may take some time. 
To abort the search, 
press DELETE. 
To add an index, use the ADD INDEX 
command from DBSTATUS or INFORMER. 


By definition, an index is a sorted ordering of 
the records in a file. 
If the current field has an 
index, the NEXT and PREVIOUS commands browse the 
file in sorted order. 
When you change the current 
field with the SELECT command, the sorted ordering 
used by these commands changes as well. 


ENTER2 can search a CHARACTER field even if you 
provide only the first or the first few of the char- 
acters in the value you are searching for. 
This 
type of search, called a "generic search," is useful 
if you do not remember the entire value or if the 
value entered in the database is spelled incorrectly 
and cannot be found when you give the entire value. 


You can perform generic searches on both in- 
dexed and non-indexed fields. 
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V.B. 
Data Checking 


When you enter data using the ADD and UPDATE 
commands, ENTER2 checks the database dictionary for 
the type and length of the field. 
If the value you 
enter does not correspond to the defined field type, 
ENTER2 displays an error message and repositions the 
cursor at the beginning of the field so you can 
correct the data. 


For example, if you enter characters in an IN- 
TEGER field, 
ENTER2 will not accept your input. 


When you are using the ADD command, you can deter- 
mine whether a field is of an arithmetic type be- 
cause ENTER2 initializes it with a 0, instead of 
with blanks. 


In INTEGER fields and LONG fields, you can 
enter only numbers. 


In DOUBLE fields and FLOAT fields, you can enter 
numbers and, optionally, a decimal point. 


In MONEY fields, you can enter numbers and, op- 
tionally, a decimal point and/or a dollar sign. 
However, ENTER2 will not display the dollar sign. 


In DATE fields, you can use any character to 
separate the month, day, and year. 
However, ENTER2 
will display the separating characters as slashes 
("/"). 


V.C. 
Concurrency Control 


Concurrency control is necessary in a multi- 
user environment to ensure that two users do not try 
to update the same 
~ecord at the same time. 


UNIX versions of INFORMIX "lock" a record while 
it is being updated. 
A locked record can be viewed 
by other users, but not updated. 
If you try to up- 
date a record that another user is working on, 
ENTER2 displays a message indicating that the record 
is locked by another user. 
. 
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VI. 
The ENTER2 Commands and Their Use 


VI.A. 
The FIND Command 


The FIND command allows you to locate records 
based on the value of one field. 
When ENTER2 lo- 
cates the record and displays it on the screen, you 
can modify it using the UPDATE command, remove it 
from the file using the DELETE command, or use any 
other command. 


Like all of ENTER2's commands, you initiate 
FIND by entering the first character in the command 
name. 
When you press F, the commands at the top of 
the screen are replaced with the choices shown in 
Figure 5. 
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,1D41 ValDa 'irat LAat ....1 


li.tift9-nu.ber 
I 
addre.. 
[ 
city 
[ 
foote,e 
[ 


bedroo.. 
[ 
bath. 
[ 
lot-ai.e 
[ 
corfter-lot 
[ ) 
.cbool. 
[ ) 


aak1n9-Price 
I 
a.le.-pric. 
[ 


broker 
I 
li.tin9-notel 
[ 


li.tin~ote2 
I 
li.tin9-note3 
[ 


Figure 5. The listings file skeleton after F has 
been typed to initiate the FIND command. 
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VI.A.1. 
The VALUE Command 


To locate a record based on the contents of 
one of its fields, 
use the 
VALUE command. 
When you 
press V, 
ENTER2 clears any data from the screen, 
leaving only the record skeleton (the field names 
and display areas)., 


The cursor, which shows where the next charac- 
ter will be typed, is positioned at the beginning of 
the current field's display area. 
Type the value 
that you are searching for and press RETURN. 


If the field in which you are searching (the 
current field) is indexed, 
ENTER2 displays the 
desired record on the screen almost immediately. 
If 
the current field does not have an index, ENTER2 
performs a sequential search looking through the 
records in the order in which they were entered. 
Since a sequential search may take significantly 
more time than searching an indexed field, 
the mes- 
sage "Searching" temporarily replaces the command 
line at the top of the screen. 


If ENTER2 finds a record that exactly matches 
the search value you entered, it displays that 
record on the screen. 
If it does not find an exact 
match, what happens next depends on whether or not 
the current field has an index. 


If the current field is indexed and there are 
no exact matches, 
ENTER2 looks for the next record 
in the indexed order and displays it. 
If the search 
value is greater than any value in the current 
field, 
ENTER2 displays the last record and the mes- 
sage "End of file." If the current field is not in- 
dexed and there are no exact matches, 
ENTER2 
displays the "End of file" message to indicate that 
it has read past the last record in its search. 


If the current field is a CHARACTER field, 
you 
can perform a generic search. 
Generic searching is 
useful when you are not sure how the field was en- 
tered. 
To initiate a generic search, enter the 
first few characters of the search value. 
ENTER2 
displays the first record it finds containing the 
partial search value. 
' 


If more than one record starts with those char- 
acters, the record ENTER2 finds may not be the one 
you want. 
You can use the NEXT command to view the 
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next record that starts with those few characters. 
The records will be in order by the 
~urrent field if 
it is indexed. 
If the current field is not indexed, 
the records will be in primary key order or in the 
order of entry. 
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bath. 
10Villo 
oomor..1ot 
"hoola 
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l18Ullg...,llcte2 
l1aUIllJ-J'ote3 


(l2 
I 
(.0.0 ftllth 't. 
(8&&"gI:0,,0 
I 
(l500 
I 
{3 
I 
{2 
I 
(l.0 
(nl 
(Ill 
{$140000.1)0 
I 
i to.OO 
I 


{JackaOIl,Robertl 
lliou clOWlltowrt. carport. 


{~ear ahopp11l9 
con~ar•• 
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Figure 6. Search results of FIND for VALUE 12 in the 
listing_nuaber field. 
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VI.A.2. 
The FIRST Command 


The FIRST command displays the first record in 
the file in order of the current field if it is in- 
dexed. 
If the current field is not indexed, FIRST 
displays the record that was entered first or the 
first record in primary key order. 


VI.A.3. 
The LAST Command 


The LAST command displays the last record in 
the file in order of the current field if it is in- 
dexed. 
If the current field is not indexed, LAST 
displays the record that was last entered or the 
last record in primary key order. 


VI.A.4. 
The SAME Command 


To continue searching for other records that 
match the search value, 
use the SAME command. 
You 
can use 
SAME repeatedly, until you reach the end of 
the file, 
to find all of the records that satisfy 
the conditions of the original FIND command. 
If 
ENTER2 does not find any other records that match 
the search value, it displays the "End of file" mes- 
sage. 
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VI.B. 
The NEXT Coaaand 


The NEXT command displays records in order of 
the current field -- the indexed order if the 
current field has an index, the order in which the 
records were entered or primary key order if the 
current field is not indexed. 


When the current field is indexed, the NEXT 
command displays the next record with the same 
search value. 
If there are no additional records 
with that search value, 
NEXT displays the next 
record in the sorted order. 
If there is no "next" record, 
ENTER2 displays 
the "End of file" message. 


VI. C. 
The PREVIOUS Co_and 


The PREVIOUS command is the complement of the 
NEXT command. 
It displays the record that sorts 
just before the current record, according to the 
sorted ordering of an indexed current field, or ac- 
cording to the order in which the records were en- 
tered or primary key order. 
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VI.D. 
The UPDATE Command 


Before a record can be changed, you must 
display it on the screen with a FIND, 
NEXT, or PRE- 
VIOUS command. 
Then you can use the UPDATE command 
by typing U. 


ENTER2 positions the cursor at the beginning of 
the display area of the current field. 
To move the 
cursor down to the next field, press RETURN. 
To 
move the cursor up to the previous field, press 
CONTROL-k. 
To move the cursor one character to the 
right within a field, press CONTROL-I. 
CONTROL-h 
moves the cursor to the left one character. 


Whenever the cursor passes the last field in 
the record, ENTER2 displays a prompt asking if the 
record is complete. 
To answer yes, press Y. 
ENTER2 


then accepts the record into the database and 
displays the message "Record updated." 


To continue updating the same record, press RE- 
TURN. 
The cursor will move to the first field in 
the record that you can modify. 


If you have finished updating the record and 
the cursor is not on the last field, 
you can press 
the ESCAPE key. 
ENTER2 immediately displays the 
"Record complete?" message. 
If you want to terminate the UPDATE command at 
any point, press the DELETE key. 
No changes that 
you have made will be accepted unless you type a Y 
after the "Record complete?" prompt. 
If you give the UPDATE command for a record 
that another user is already 
updating, ENTER2 
displays the message, 
"Record is locked by another 
user" and does not initiate the UPDATE command. 


: 
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C~ds. rind "st PrevioDa Update Add Delete Select 
~drav Bye ? 
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Figure 7. Updated record showing "Record complete?" 
prompt in the message area. 
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VI.E. 
The ADD Command 


When you type A to execute the ADD command, 
ENTER2 clears the screen 
o~ any data currently 
displayed in the record skeleton and positions the 
cursor at the beginning 
o~ the 
~irst 
~ield's display 
area. 
When you have 
~inished entering data in the 


~irst 
~ield, press RETURN to move the cursor to the 
next 
~ield. 
I~ you 
~ill the 
~ield, ENTER2 automati- 
cally moves the cursor to the next 
~ield, without 
requiring that you press RETURN. 


The same cursor motion keys that are used with 
UPDATE are used with ADD. 
RETURN moves the cursor 
down a 
~ield; CONTROL-k moves it up a 
~ield. 


CONTROL-I moves the cursor one character to the 
right within a field; 
CONTROL-h moves it one charac- 
ter to the left. 


Whenever the cursor passes the last 
~ield in 
the record, 
ENTER2 displays a prompt asking if the 
record is complete. 
To answer yes, press Y. 
ENTER2 
then accepts the record into the database and 
displays the "Record added" message. 


If the record is not complete, you can add to 
or modify it. 
Press RETURN and ENTER2 moves the 
cursor to the first field you can modify. 


If the record is complete and the cursor is not 
at the last field, 
you need not keep pressing RE- 
TURN. 
You can press ESCAPE at any time and ENTER2 
displays the "Record complete?" prompt. 
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VI.F. 
The DELETE Command 


To delete a record, you must first find it and 
display it on the screen using the FIND, 
NEXT, or 
PREVIOUS command. 
Then type D. 
ENTER2 responds 
wi th the word "Delete?" 


Press Y or N to confirm or abandon the dele- 
tion. 
When ENTER2 has deleted the record, it 
displays the message "Record deleted." 


VI. G. 
The SELECT Colllllland 


With the SELECT command, you can change 


e 
the database you are working with 


e 
the file you are working with 


e 
the current page (if the file has so many 
fields that they do not all fit on the screen 
at once) 


the current field 


When you press S to begin the SELECT command, 
the commands at the top of the screen are replaced 
with the options shown in Figure 8. 


You can abort the SELECT command, like all 
ENTER2 commands, by pressing DELETE. 
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Select: 
Fleld Page Kenu-of-fl1•• Database ? 
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Figure 8. The SELECT command after the S key 
ha~. 


been pressed. 
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VI.G.1. 
FIELD 


When you begin an ENTER2 session, ENTER2 looks 
for the first indexed field and 
makes it the 
current field. 
If no fields are indexed, ENTER2 
makes the first field listed in the schema the 
current field. 


To change the current field during an ENTER2 
session, press S for SELECT and then F for Field. 
ENTER2 prompts for the name of the new current 
fie+d-, as shown in Figure 9. 


Then type the name of any field in the data- 
base. 
If the field is in the current file, the 
current file remains the same. 
If the field is in another file in the same da- 
tabase, 
ENTER2 automatically changes the current 
file to the file containing the selected field. 
This is possible because of the requirement that 
field names be unique across a database. 


Figure 10 shows the screen after the 
agent number field in the agents file has been 
selected. 


24 
INFORMIX 


ENTER2 Screen-Oriented Data Entry Program 


Select Held. 
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Figure 9. The SELECT command after the S key has 
been pressed, and the F key has been pressed to in- 
dicate the Field option. 


INFORMIX 
25 


ENTER2 Screen-Oriented Data Entry Program 


co..andal rind "at Pre.ioua Opdate Add Delete Select aedraw 91e? 
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Figure 10. The SELECT command after the agent number 
field has been selected. 
The agents file automati- 
cally becomes the selected file. 
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VI.G.2. 
MENU-OF-FILES 


Another way to change the current file is to 
use the Menu-of-files option of the SELECT command. 
If you choose the Menu-of-files option by typing M, 
ENTER2 displays the list of files in the database 
and prompts you to enter a filename, as shown in 
Figure 11. 
If there is only one file in the database, that 
file is reselected automatically when you choose the 
Menu-of-files option. 


When you select a new current file, its record 
skeleton is displayed on the screen. 
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!he file. in the databa.e "realty" are li.tad balov. 
..ent. 
Inter your choice. 
)li.tin9~ 


li.tin9· 


Figure 11. The SELECT command after you press S for 
SELECT, M for Menu-of-files, and then select 
listings as the current file. 
After you press RE- 
TURN, the skeleton of the listings file is 
displayed. 
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VI.G.3. 
PAGE 


The Page option displays the next page or 
screen of a multi-page record. 
A multi-page record 
has more fields than will fit on a terminal screen 
at one time. 
If the last page of the record is on 
the screen, the Page option displays the first page. 


VI.G.4. 
DATABASE 


If you press D for the Database option, 
ENTER2 
prompts you to give the name of another database, as 
shown in Figure 12. 


The database you enter must be in the current 
operating system directory. 


: 
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~lee.e entec Che 4atabee. you would 11k. to .elect. 


Figure 12. The SELECT command after you press S for 
SELECT and D for the DATABASE option. 
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VI.H. 
The REDRAW Command 


The REDRAW command is used to redisplay what is 
on your screen if it becomes garbled during an 
ENTER2 session. 


This might occur if another user sends a mes- 
sage to you. 
Or, if you are using a computer via 
phone lines, your terminal might try to interpret 
noise on the line and display unwanted characters. 


If you suspect that what is displayed on your 
screen is not what is stored in the computer's 
memory, you can use the REDRAW command to check. 
If the REDRAW command has no effect, try turn- 
ing the terminal off and then on again. 


The REDRAW command does not affect the contents 
of the database. 


VI.I. 
The BYE Command 


To end an ENTER2 session, type B for BYE. 


> bye 


BYE 


Program over. 
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V. 
Appendix - Error Messages 


error 3008: 


Duplicate value for a unique key. 


error 3010: 


Field "fie1dname" not found. 


error 3011: 


File "filename" not found. 


error 3014: 


No current record. 


error 3015: 


Database "database name" not found. 


error 3016: 


File "filename" not found. 


error 3017: 


End of file. 


error 3018: 


Non-key fie 1d. 


error 3019: 


Beginning of file. 


error 3020: 


NEXT or PREVIOUS can only be used after a successful 
keyed search. 
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error 3021: 


Record not found. 


error 3023: 


SAME can only be used after a successful non-key 
search. 


error 3024: 


No data in this file. 


error 3026: 


Invalid data for field. 


error 3027: 


The maximum number of significant digits for a dou- 
ble is 15. 


;;-. 


error 3028: 


Record or file is locked by another user. 


error 3029: 


Exponent too large. 


error 3030: 


Record has already been deleted. 


error 3031: 


Record was deleted or changed by another user. 


error 3032: 


Record was deleted or changed by another user. 
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error 3033: 


File is exclusively locked by another user. 


error 3034: 


Permission not granted for reading this file. 


error 3035: 


Permission not granted for updating this file. 


error 3036: 


Permission not granted for adding records to this 
.file • 


.~rror 3037: 


Permissio.n not granted for deleting records from 
this filE:!. 


error 303e: 


Read only permission allowed on this file. 
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